Shopping Observations
Individual product observations from AI shopping surfaces.
GET /api/v1/shopping-observations returns the raw observations behind the
shopping aggregates: one row per product
seen in an AI shopping result. 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_mode, ai_overview, chatgpt, or copilot. |
capture_source | serp (Google surfaces) or scraper (ChatGPT capture). |
matched_product_id | Restrict to one catalog product. |
run_id | Restrict to one run's observations. |
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 product was observedprompt_id: the tracked prompt whose answer carried the productposition: 1-based rank within the shopping resulttitle,brand_text,merchant: the product as displayedprice_centsandcurrency: the observed price, when shownratingandreview_count: displayed review data, when shownmatched_product_idandmatch_confidence: the catalog product this observation resolved to (exact,strong, orfuzzy), or null when no catalog product matchescaptured_at: when the observation 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/shopping-observations?surface=ai_mode&since=2026-08-01"Use this resource to audit exactly which products AI surfaces showed for your prompts, at what positions and prices, and which merchants carried them.