Before kicking off a seasonal campaign, it pays to see what last year's playbook looked like. This recipe uses full-text search plus a date window to surface every ad whose copy, title, or brand name matches a given keyword in a given period.
Endpoint used
GET /open/v1/ads
New to the API? Read the Quickstart for auth and the response envelope.
The query
curl -sS \
-H "X-API-Key: $ATRIA_API_KEY" \
"https://api.tryatria.com/open/v1/ads?query=black+friday&language=en&start_date=2024-11-01&end_date=2024-11-30&sort_by=most_active&page_size=50"import os
import requests
resp = requests.get(
"https://api.tryatria.com/open/v1/ads",
headers={"X-API-Key": os.environ["ATRIA_API_KEY"]},
params={
"query": "black friday",
"language": "en",
"start_date": "2024-11-01",
"end_date": "2024-11-30",
"sort_by": "most_active",
"page_size": 50,
},
timeout=30,
)
for ad in resp.json()["data"]["items"]:
print(f"[{ad['cta_type']:<15}] {ad['brand_name']:<25} — {ad['title']}")const url = new URL("https://api.tryatria.com/open/v1/ads");
url.searchParams.set("query", "black friday");
url.searchParams.set("language", "en");
url.searchParams.set("start_date", "2024-11-01");
url.searchParams.set("end_date", "2024-11-30");
url.searchParams.set("sort_by", "most_active");
url.searchParams.set("page_size", "50");
const resp = await fetch(url, {
headers: { "X-API-Key": process.env.ATRIA_API_KEY },
});
const { data } = await resp.json();
for (const ad of data.items) {
console.log(
`[${(ad.cta_type ?? "").padEnd(15)}] ${(ad.brand_name ?? "").padEnd(25)} — ${ad.title ?? ""}`,
);
}What query actually searches
query actually searchesquery runs full-text search across:
titlebodybrand_name
It is not a regex or boolean query. Two-word phrases like "black friday" match ads where both terms appear; quoting is unnecessary.
Parameter notes
| Parameter | Effect |
|---|---|
query | Free-text. URL-encode spaces as + or %20. |
language | ISO 639-1 code, repeatable. Filters by detected ad language. |
start_date | Inclusive lower bound on the ad's launch date. |
end_date | Inclusive upper bound on the ad's launch date. |
sort_by=most_active | Surfaces ads that ran the longest — strong signal for "this worked." |
Going further
- Pair with
display_format=videoto study video copy specifically. - Walk the cursor to pull the full corpus, then break down by
cta_typeto see which CTAs dominated the campaign. - Re-run year-over-year with the same
queryand a shifted date window to track how a theme's competitive landscape is evolving.
