Core Concepts

Understanding the data model makes the API endpoints predictable. Every endpoint maps to one or more of these entities.

---

Prompt

A prompt is a tracked query — the question being monitored for brand mentions. Examples: "best CRM software", "top project management tools for remote teams", "which email marketing platform is best for SaaS".

Each prompt is associated with:

• A brand — whose mentions you're tracking in answers to this query
• A country — the geographic context for the scan (e.g., US, GB, DE)
• An optional topic — an organizational grouping

Prompts are scanned daily. Every prompt in your account enters the scan queue at the start of each daily cycle (03:00 UTC). The scan runs the prompt against every configured AI engine and stores the results.

A prompt consumes one unit of your prompt quota regardless of how many engines or countries it's configured for.

---

Run

A run (scan result) is one execution of a prompt against one AI engine on one day. If you have one prompt configured for ChatGPT and Gemini, each daily cycle produces two runs for that prompt.

Each run contains:

• answer_text — the full raw answer returned by the AI engine
• brand_mentioned — boolean, whether the brand appeared in the answer
• brand_sentiment, categorical label: positive, neutral, negative, or not_mentioned. It is never not_mentioned when brand_mentioned is true; an answer that names the brand without opinion is neutral.
• sentiment_score — 0–100 numeric score from LLM analysis
• brand_position, 1-based position in a numbered list in the answer; null when the answer has no numbered list or the brand is not mentioned
• citations — list of all URLs cited in the answer
• engine — which AI engine produced this answer
• country — the country context
• scanned_at, ISO 8601 timestamp of the scan

answer_text keeps Markdown formatting (line breaks, lists) for ChatGPT and Gemini. For Google, map-widget labels and links relative to google.com are removed. Runs with no answer text (for example, Google showed no AI Overview) are not stored, so they do not count as scans or lower visibility.

Runs are the atomic unit of data. Everything else — visibility scores, citation aggregates, timelines — is computed from runs.

---

Citation

A citation is a single URL cited within an AI answer. Each run can have zero or more citations.

Citations are normalized:

• domain — the hostname extracted from the URL (e.g., g2.com)
• url — the full path
• domain_type — classified category (e.g., review_site, competitor, news, wiki)

GET /v1/aeo/sources/top-domains returns one row per domain; its domain_type is the most common type for that domain.

The domain-level aggregation (GET /v1/aeo/sources/domains) and URL-level detail (GET /v1/aeo/sources/detail) are both built from citation records.

---

Brand

A brand is an entity you're tracking — either your own brand or a competitor.

Key fields:

• is_own_brand — true for your brand, false for competitors
• domain, the brand's primary domain
• extra_domains, optional list of other sites the brand owns (for example danhotels.co.il next to danhotels.com). A citation of any of them counts as "cited own site". Settable on POST /v1/aeo/brands and PATCH /v1/aeo/brands/{id}.
• aliases, alternative names matched in answers
• parent_brand_id, attaches a competitor to one of your own brands (it is added to that brand's prompts and grouped under it). It does nothing on your own brands.

For variants and sister sites of your own brand (for example Leonardo hotels under Fattal), use aliases for the names and extra_domains for the sites.

PATCH /v1/aeo/brands/{id} accepts name, domain, aliases and extra_domains. aliases and extra_domains replace the whole list. Changes apply to new scans only; answers already scanned keep their original matches.

An advocate is not needed for AI visibility tracking. It is only used to draft Reddit replies to brand mentions (Brand Monitor) and can be added later.

Competitor ids also work on GET /v1/aeo/visibility/explain and GET /v1/aeo/sentiment/explain: they explain the competitor's mentions on your prompts (competitor sentiment_score is null). GET /v1/aeo/brands/ranking lists competitors alongside your own brands.

You can track competitor brands using the same API. Set is_own_brand: false when creating them. Competitor brands count against your prompt quota the same way your own brand does.

---

Topic

A topic is an organizational grouping for prompts. You might create topics like "Competitor Comparison", "Category Awareness", or "Feature Queries" to group related prompts and filter visibility reports by topic.

Topics are optional. Prompts without a topic still get scanned normally.

---

Engines

GET /v1/aeo/engines returns 6 entries, each {id, name, active}:

active is true only for engines your organization is scanned on right now. An engine that fails repeatedly also shows active: false temporarily, so the number of active engines can change; call GET /v1/aeo/engines for the current state.

Engines are chosen per organization, never per prompt: the prompt endpoints take no engines field. Each visibility and run endpoint accepts an engine filter parameter.

---

Countries

Country targeting uses ISO 3166-1 alpha-2 codes (e.g., US, GB, DE, FR). The country affects which regional version of the AI engine is queried.

Use GET /v1/aeo/countries to fetch the full list of supported codes and display names. A prompt with country: "US" produces US-context answers; the same query with country: "DE" may produce different citations and brand mentions.

---

Scan cycle

Scans run once daily at 03:00 UTC. BrightData infrastructure queries each AI engine, captures the response, and stores the raw answer. LLM analysis (Gemini 2.0 Flash) runs immediately after capture to extract brand mentions, sentiment, and brand position.

Results are typically available 1–4 hours after the scan cycle starts — i.e., by 04:00–07:00 UTC.

New prompts created after the scan cycle starts enter the queue for the next day's cycle. There is no on-demand scan endpoint.

---

Data retention

Scan results are retained indefinitely for active accounts. If you cancel your Pro plan, results are retained for 90 days from the cancellation date. After 90 days, all scan data is permanently deleted.

Historical backfill is not available. Data starts from the day the prompt was first created and scanned.