Search & Filter Ads

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

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

fetch('https://api.aisa.one/apis/v1/foreplay/discovery/ads', 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/discovery/ads",
  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/discovery/ads"

	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/discovery/ads")

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

discovery

ads

Search & Filter Ads

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

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

fetch('https://api.aisa.one/apis/v1/foreplay/discovery/ads', 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/discovery/ads",
  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/discovery/ads"

	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/discovery/ads")

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
}

Search across the Foreplay ad index with a text query plus filters (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 — image/video URLs, transcription, brand metadata, targeting, and more. Use cursor + limit (max 250) to page. 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

Authorizations

Authorization

string

header

required

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

Query Parameters

query

string

Search text for ad name or description. Leave empty to search all ads with filters only.

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.

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: accessories, app/software, beauty, business/professional, education, entertainment, fashion, food/drink, health/wellness, home/garden, jewelry/watches, other, parenting, pets, real estate, service business, medical, charity/nfp, kids/baby 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.

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

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

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

Search & Filter Ads

Authorizations

Query Parameters

Response