Get Ads by Brand IDs

curl --request GET \
  --url https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "metadata": {
    "success": true,
    "status_code": 200,
    "count": 1,
    "cursor": null
  },
  "data": [
    {
      "id": "abc123",
      "brand_id": "bYeKOahyGopmGKMHiWit",
      "brand_name": "Nike",
      "display_format": "video",
      "publisher_platform": "facebook",
      "live": true
    }
  ],
  "error": null
}

GET

https://api.aisa.one/apis/v1

foreplay

brand

getAdsByBrandId

Get Ads by Brand IDs

curl --request GET \
  --url https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "metadata": {
    "success": true,
    "status_code": 200,
    "count": 1,
    "cursor": null
  },
  "data": [
    {
      "id": "abc123",
      "brand_id": "bYeKOahyGopmGKMHiWit",
      "brand_name": "Nike",
      "display_format": "video",
      "publisher_platform": "facebook",
      "live": true
    }
  ],
  "error": null
}

Retrieve ads for one or more known Foreplay brand IDs (brand_ids, comma-separated), applying the same rich filter set as discovery (live status, display format, publisher platform, niche, market target, language, video/running duration, date range, order). Each result in data[] is a full ad object. Use cursor + limit (max 250) to page. ⚠️ Accepts brand_ids only. page_id lookup is NOT supported on the AIsa gateway — resolve a domain to its ad_library_id / brand id via get_foreplay-getbrandsbydomain first. Passing a page id in brand_ids returns HTTP 200 with count: 0 (silently treated as an unknown brand). This is intentional P0 scoping, documented as a known limitation. display_format accepts exactly these 11 values: carousel, dco, dpa, event, image, multi_images, multi_medias, multi_videos, page_like, text, video. **Billing:

0.02625 per item returned in `data[]`; empty results and errors are not charged.** One credit per ad; a call with `limit≤50` costs at most

1.3125. Example: GET /foreplay/brand/getAdsByBrandId?brand_ids=bYeKOahyGopmGKMHiWit (Nike, resolved via getBrandsByDomain?domain=nike.com). Related: get_foreplay-getbrandsbydomain (resolve brand_ids from a domain), get_foreplay-discovery-ads, get_foreplay-brand-analytics.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

brand_ids

array

required

Brand ID(s) to search for. Can be a single ID or multiple IDs separated by commas.

live

string

Filter ads by live status. true means currently active ads, false means inactive ads. Leave empty to include both.

display_format

enum<string>

Filter by one or more display formats. Available formats (11): carousel, dco, dpa, event, image, multi_images, multi_medias, multi_videos, page_like, text, video Example: ?display_format=video&display_format=carousel

Available options:

carousel,

dco,

dpa,

event,

image,

multi_images,

multi_medias,

multi_videos,

page_like,

text,

video

publisher_platform

enum<string>

Filter by one or more publisher platforms. Available platforms: facebook, instagram, audience_network, messenger, tiktok, youtube, linkedin, threads, whatsapp Example: ?publisher_platform=facebook&publisher_platform=instagram

Available options:

facebook,

instagram,

audience_network,

messenger,

tiktok,

youtube,

linkedin,

threads,

whatsapp

niches

string

Filter by one or more niches. Available niches: travel, food, fashion, beauty, health, technology, automotive, finance, education, entertainment, sports, home, pets, business, other Example: ?niches=travel&niches=fashion

market_target

string

Filter by market target. Available targets: b2b (business-to-business), b2c (business-to-consumer) Example: ?market_target=b2b

languages

string

Filter by languages. Accepts various language formats: 'french', 'FR', 'romanian', 'ro', 'english', 'en', etc. Example: ?languages=en&languages=fr

video_duration_min

string

Filter ads by minimum video duration in seconds. Only applies to video ads.

video_duration_max

string

Filter ads by maximum video duration in seconds. Only applies to video ads.

running_duration_min_days

string

Filter ads by minimum running duration in days. Must be a positive integer.

running_duration_max_days

string

Filter ads by maximum running duration in days. Must be a positive integer.

start_date

string

Start date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS', or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g. '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To get all ads from a specific day, set end_date to 'YYYY-MM-DD 23:59:59' or to the next day at '00:00:00'. Examples: start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59.

end_date

string

End date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS', or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g. '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To include all results for a given day, set end_date to 'YYYY-MM-DD 23:59:59' or to the next day at '00:00:00'. Examples: start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59.

order

enum<string>

default:newest

Order of results: 'newest' (default), 'oldest', 'longest_running', or 'most_relevant'. Sorts ads by creation date, longest running duration, or relevance to the search query.

Available options:

newest,

oldest,

longest_running,

most_relevant

cursor

string

Cursor for pagination. Use the cursor value from the previous response's metadata to get the next page of results.

limit

integer

default:10

Pagination limit (max 250). Controls the number of ads returned per request.

Required range: x <= 250

collect

string

default:false

Best-effort live fallback. If the cached results are empty and collect=true, the API translates each brand id to its Meta page id (adlibraryid), kicks off a live fetch through our Spyder pipeline, and polls for ~30 seconds. Returns whatever is available at the end of the window — may still be empty if a brand has no Meta page on file, the page is restricted, deleted, or simply isn't running ads. Not perfect — use it as a fallback when the regular response is empty, not as a default.

Response

200 - application/json

JSON envelope with metadata and a data[] array of ad objects. Each ad in data[] counts as one billed item.

The response is of type object.

Overview

Chat API

Embeddings & Rerank

Search API

Perplexity API

Financial API

Twitter API

Reddit API

Instagram API

Pinterest API

Scholar API

WaveInflu API

Prediction Market API

CoinGecko

DataForSEO

AgentMail

Apollo

Ahrefs API

Semrush API

Foreplay API

SimilarWeb API

Essentials

Get Ads by Brand IDs

Authorizations

Query Parameters

Response