curl --request GET \
--url https://api.aisa.one/apis/v1/foreplay/discovery/ads \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aisa.one/apis/v1/foreplay/discovery/ads"
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/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))
}HttpResponse<String> response = Unirest.get("https://api.aisa.one/apis/v1/foreplay/discovery/ads")
.header("Authorization", "Bearer <token>")
.asString();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
}Discovery Ads
Search across the Foreplay ad index (100M+ ads) with a text query plus filters. Each result in data[] is a full ad object (image/video URLs, transcription, brand metadata, targeting, and more).
Billed $0.02625 per item returned in data[] (1 credit per item); empty results and 4xx/5xx errors are not charged.
curl --request GET \
--url https://api.aisa.one/apis/v1/foreplay/discovery/ads \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aisa.one/apis/v1/foreplay/discovery/ads"
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/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))
}HttpResponse<String> response = Unirest.get("https://api.aisa.one/apis/v1/foreplay/discovery/ads")
.header("Authorization", "Bearer <token>")
.asString();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
}授权
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
查询参数
Cursor for pagination. Use the cursor value from the previous response's metadata to get the next page of results.
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
carousel, dco, dpa, event, image, multi_images, multi_medias, multi_videos, page_like, text, video 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.
Filter by languages.
Accepts various language formats: 'french', 'FR', 'romanian', 'ro', 'english', 'en', etc.
Example: ?languages=en&languages=fr
Pagination limit (max 250). Controls the number of ads returned per request.
x <= 250Filter ads by live status. true means currently active ads, false means inactive ads. Leave empty to include both.
Filter by market target.
Available targets: b2b (business-to-business), b2c (business-to-consumer)
Example: ?market_target=b2b
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
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.
newest, oldest, longest_running, most_relevant 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
facebook, instagram, audience_network, messenger, tiktok, youtube, linkedin, threads, whatsapp Search text for ad name or description. Leave empty to search all ads with filters only.
Filter ads by maximum running duration in days. Must be a positive integer.
Filter ads by minimum running duration in days. Must be a positive integer.
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.
Filter ads by maximum video duration in seconds. Only applies to video ads.
Filter ads by minimum video duration in seconds. Only applies to video ads.
响应
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.