Get Ads By Brand Id

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

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

GET

https://api.aisa.one

apis

foreplay

brand

getAdsByBrandId

Get Ads By Brand Id

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

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

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: per item returned in data[]; empty results and errors are not charged. Current prices are on aisa.one/api. One credit per ad; a call with limit≤50 bills at most 50 items 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.

Request contract

Method and path: GET /apis/v1/foreplay/brand/getAdsByBrandId
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/foreplay/brand/getAdsByBrandId
brand_ids: query; required
collect: query; optional
cursor: query; optional
display_format: query; optional
end_date: query; optional
languages: query; optional
limit: query; optional
live: query; optional
market_target: query; optional
niches: query; optional
order: query; optional
publisher_platform: query; optional
running_duration_max_days: query; optional
running_duration_min_days: query; optional
start_date: query; optional
video_duration_max: query; optional
video_duration_min: query; optional
Runtime facts: 799c2645862e25f3076e45d5e7d545772f57444689dd138cd88f92c37554b81c

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "get_ads_by_brand_ids",
  "method": "GET",
  "path": "/apis/v1/foreplay/brand/getAdsByBrandId",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [
    {
      "description": "Brand ID(s) to search for. Can be a single ID or multiple IDs separated by commas.",
      "in": "query",
      "name": "brand_ids",
      "required": true,
      "schema": {
        "type": "array"
      }
    },
    {
      "description": "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.",
      "in": "query",
      "name": "collect",
      "required": false,
      "schema": {
        "default": "false",
        "type": "string"
      }
    },
    {
      "description": "Cursor for pagination. Use the cursor value from the previous response's metadata to get the next page of results.",
      "in": "query",
      "name": "cursor",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter by one or more display formats.\nAvailable formats (11): carousel, dco, dpa, event, image, multi_images, multi_medias, multi_videos, page_like, text, video\nExample: `?display_format=video&display_format=carousel`\n\n",
      "in": "query",
      "name": "display_format",
      "required": false,
      "schema": {
        "enum": [
          "carousel",
          "dco",
          "dpa",
          "event",
          "image",
          "multi_images",
          "multi_medias",
          "multi_videos",
          "page_like",
          "text",
          "video"
        ],
        "type": "string"
      }
    },
    {
      "description": "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.",
      "in": "query",
      "name": "end_date",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter by languages.\nAccepts various language formats: 'french', 'FR', 'romanian', 'ro', 'english', 'en', etc.\nExample: `?languages=en&languages=fr`\n\n",
      "in": "query",
      "name": "languages",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Pagination limit (max 250). Controls the number of ads returned per request.",
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "default": 10,
        "maximum": 250,
        "type": "integer"
      }
    },
    {
      "description": "Filter ads by live status. `true` means currently active ads, `false` means inactive ads. Leave empty to include both.",
      "in": "query",
      "name": "live",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter by market target.\nAvailable targets: b2b (business-to-business), b2c (business-to-consumer)\nExample: `?market_target=b2b`\n\n",
      "in": "query",
      "name": "market_target",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter by one or more niches.\nAvailable niches: travel, food, fashion, beauty, health, technology, automotive, finance, education, entertainment, sports, home, pets, business, other\nExample: `?niches=travel&niches=fashion`\n\n",
      "in": "query",
      "name": "niches",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "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.",
      "in": "query",
      "name": "order",
      "required": false,
      "schema": {
        "default": "newest",
        "enum": [
          "newest",
          "oldest",
          "longest_running",
          "most_relevant"
        ],
        "type": "string"
      }
    },
    {
      "description": "Filter by one or more publisher platforms.\nAvailable platforms: facebook, instagram, audience_network, messenger, tiktok, youtube, linkedin, threads, whatsapp\nExample: `?publisher_platform=facebook&publisher_platform=instagram`\n\n",
      "in": "query",
      "name": "publisher_platform",
      "required": false,
      "schema": {
        "enum": [
          "facebook",
          "instagram",
          "audience_network",
          "messenger",
          "tiktok",
          "youtube",
          "linkedin",
          "threads",
          "whatsapp"
        ],
        "type": "string"
      }
    },
    {
      "description": "Filter ads by maximum running duration in days. Must be a positive integer.",
      "in": "query",
      "name": "running_duration_max_days",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter ads by minimum running duration in days. Must be a positive integer.",
      "in": "query",
      "name": "running_duration_min_days",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "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.",
      "in": "query",
      "name": "start_date",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter ads by maximum video duration in seconds. Only applies to video ads.",
      "in": "query",
      "name": "video_duration_max",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Filter ads by minimum video duration in seconds. Only applies to video ads.",
      "in": "query",
      "name": "video_duration_min",
      "required": false,
      "schema": {
        "type": "string"
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "cost_contract": "response_count",
    "customer_multiplier": 1.0,
    "customer_pricing": "provider_cost_multiplier",
    "default_request_estimate_usd": 0.875,
    "estimate_source": "profile_seed",
    "evidence_source": "response_body",
    "maximum_units": 50,
    "unit": "provider_credit",
    "unit_rate_usd": 0.0
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

Usage-based billing; Default request estimate: $0.875 USD (not a fixed price). Declared unit rate: $0 USD per provider_credit. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Default request reference estimate (USD): 0.875
Declared unit rate (USD): 0.0
Billing unit: provider_credit
Cost contract: response_count
Published reference multiplier: 1.0
Declared maximum count/units: 50
Settlement evidence source: response_body

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.

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.

cursor

string

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

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

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.

languages

string

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

limit

integer

default:10

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

Required range: x <= 250

live

string

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

market_target

string

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

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

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

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

running_duration_max_days

string

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

running_duration_min_days

string

Filter ads by minimum 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.

video_duration_max

string

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

video_duration_min

string

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

Response

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

Models

Search & Research

Finance & Crypto

Social & Media

SEO & Web Intel

Sales & Email

Travel & Other

Get Ads By Brand Id

Request contract

Cost and request rules

Authorizations

Query Parameters

Response

​Request contract

​Cost and request rules

Authorizations

Query Parameters

Response

Request contract

Cost and request rules