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
• sentiment_score — 0–100 numeric score from LLM analysis
• brand_position — ordinal rank of the first brand mention in the answer (1 = first), null if not mentioned
• citations — list of all URLs cited in the answer
• engine — which AI engine produced this answer
• country — the country context
• scanned_at — timestamp of the scan

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)

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
• parent_brand_id — optional, for grouping brand variants under a parent

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

The 4 supported AI engines:

Use GET /v1/aeo/engines to fetch the current list programmatically. 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.