Jump to Content

Keyword Ads Search

Find every "Black Friday" ad shipped last November — across all brands.

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&active_since=2025-11-01&launched_before=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",
        "active_since": "2025-11-01",
        "launched_before": "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("active_since", "2025-11-01");
url.searchParams.set("launched_before", "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

Parameter	Effect
`query`	Free-text. URL-encode spaces as `+` or `%20`.
`language`	ISO 639-1 code, repeatable. Filters by detected ad language.
`active_since`	Keeps ads still running on or after this date, whenever they launched.
`launched_before`	Inclusive upper bound on the ad's launch date.
`order=most_active`	Surfaces ads that ran the longest — strong signal for "this worked."

The two date bounds are what scopes this to the campaign: an ad had to launch on or before the window closes, and still be running once it opens. Using a launch-date range instead would drop everything that started earlier and ran through the period — usually the strongest performers.

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.

Updated about 4 hours ago

Did this page help you?