Ad Observations
Sponsored placements observed in AI answers on tracked prompts.
GET /api/v1/ads returns one row per sponsored placement observed in an AI
answer on a tracked prompt. Rows from the weekly Google surface runs carry a
run_id joinable to runs; rows from the ChatGPT capture
add-on stand alone with run_id null.
Filters
| Parameter | Meaning |
|---|---|
prompt_id | Restrict to one tracked prompt. |
surface | ai_overview, ai_mode, or chatgpt. |
capture_source | serp (Google surfaces) or scraper (ChatGPT capture). |
advertiser_domain | Restrict to one advertiser domain. |
advertiser_brand_id | Restrict to placements matched to one brand. |
run_id | Restrict to one run's placements. |
since / until | Bounds for captured_at (ISO timestamp). |
Standard parameters (limit, offset, format=csv) work as described in
Pagination, filtering, and errors.
Key fields
observation_id: stable identifiersurfaceandcapture_source: where and how the placement was observedprompt_id: the tracked prompt whose answer carried the adposition: 1-based rank within the answer's ad blockad_unit_type: the placement format, when the surface reports onetitleanddescription: the ad as displayedtarget_url: the displayed destinationadvertiser_domain: the advertiser's resolved domain. Tracking links are followed server-side to the canonical destination; until a link resolves, this holds the displayed domain.advertiser_brand_id: the tracked or detected brand this advertiser matched, or null for unrecognized advertisersis_rendered: whether the placement actually displayed in the answer. Google-surface rows are always true; ChatGPT capture distinguishes rendered placements from ad requests that never showed.captured_at: when the placement was recorded
Rows are ordered by captured_at descending with observation_id as the
tiebreak, so offset pagination is stable.
Example
curl -H "Authorization: Bearer $AEO_API_KEY" \
"https://app.citlyze.com/api/v1/ads?surface=ai_mode&since=2026-08-01"Use this resource to audit which advertisers bought placements on your prompts, where those placements ranked, and which of them belong to brands you track.