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/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 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.
sort_by=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_type to see which CTAs 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.