Keyword Ads Search

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/ad-library/search

The query

curl -sS \
  -H "X-API-Key: $ATRIA_API_KEY" \
  "https://api.tryatria.com/open/v1/ad-library/search?query=black+friday&language=en&start_date=2025-11-01&end_date=2025-11-30&order=most_active&page_size=50"
import os
import requests

resp = requests.get(
    "https://api.tryatria.com/open/v1/ad-library/search",
    headers={"X-API-Key": os.environ["ATRIA_API_KEY"]},
    params={
        "query": "black friday",
        "language": "en",
        "start_date": "2025-11-01",
        "end_date": "2025-11-30",
        "order": "most_active",
        "page_size": 50,
    },
    timeout=30,
)
resp.raise_for_status()
for ad in resp.json()["data"]["items"]:
    print(f"[{(ad.get('cta_text') or ''):<15}] {ad['brand_name']:<25} — {ad['title']}")
const url = new URL("https://api.tryatria.com/open/v1/ad-library/search");
url.searchParams.set("query", "black friday");
url.searchParams.set("language", "en");
url.searchParams.set("start_date", "2025-11-01");
url.searchParams.set("end_date", "2025-11-30");
url.searchParams.set("order", "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_text ?? "").padEnd(15)}] ${(ad.brand_name ?? "").padEnd(25)} — ${ad.title ?? ""}`,
  );
}

What query actually searches

query runs full-text search across:

  • title
  • body
  • brand_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

ParameterEffect
queryFree-text. URL-encode spaces as + or %20.
languageISO 639-1 code, repeatable. Filters by detected ad language.
start_dateInclusive lower bound on the ad's launch date.
end_dateInclusive upper bound on the ad's launch date.
order=most_activeSurfaces ads that ran the longest — strong signal for "this worked."

Going further

  • Pair with display_format=video to study video copy specifically.
  • Walk the cursor to pull the full corpus, then break down by cta_text to see which CTA labels dominated the campaign.
  • Re-run year-over-year with the same query and a shifted date window to track how a theme's competitive landscape is evolving.