Documentation

Knowledge base

Everything you need to know about GEO Scout

Developer API

Analytics Export REST API

Programmatically pull brand analytics from GEO Scout — for BI tools, custom dashboards, and automation.

What you get

  • —Up to 90 days of brand analytics in a single request
  • —17 datasets: prompts, sources, AI responses, Share of Voice, brand perception, competitors with their directory, timelines, gaps, and ads
  • —CSV archive (zip with multiple files) or JSON bundle
  • —Identical data to the in-dashboard export button

Authentication

Endpoint accepts a Bearer token. Same tokens as MCP integration — Personal Access Token (PAT) or OAuth token.

Generate a PAT on the /mcp page. Requires scope mcp:read (granted by default).

Dataset catalog

26 datasets cover answers, citations, metrics, ad history, product cards and E-com recommendations. Select any combination.

KeyWhat's inside
promptsBrand prompts with per-period metrics: reach, SoV, sentiment for each prompt.
source_domainsCitations rolled up per domain, most-cited first — the domain table from the Sources page: used (every appearance) / cited (of those, real citations), citation_share_pct, priority_score, unique_urls, brand_confirmed_urls / brand_not_found_urls / brand_unchecked_urls (how many URLs of the domain were verified to mention the brand on the page, read without a mention, not checked yet), prompts_count, prompt_ids (joinable to the prompts dataset), clusters and providers.
source_pagesThe same rolled up per URL: source_title, used / cited, citation_share_pct, priority_score, brand_mentioned_on_page (true — the brand name was found on the page, false — the page was read and the brand is not on it, null — not checked yet), brand_page_check (confirmed / not_found / unverifiable / not_checked), brand_page_snippets (up to 20 page fragments around the brand mentions; empty unless confirmed), prompts_count, prompt_ids, clusters and providers.
responsesRaw AI response rows: prompt_id, response_id, provider, sentiment, brand position, citation type, plus answered_from_memory (the engine replied from memory instead of searching), forced_search (we asked it to look up current data) and forced_search_error. Full answer text and the pre-search answer are included only with includeResponseText: true. Also includes prompt_text, cluster_id, cluster, brand_presence_level, brand_presence_reason, brand_comparison, brand_comparison_extracted, brand_argued, brand_standing_note, directly_recommended_entities and directly_recommended_entity_ids, stronger_competitors and stronger_competitor_ids, competitor_presence (array of entity_id, entity_name, presence_level, level_reason, recommendation, comparison, comparison_extracted, argued, sentiment). Level and comparison values follow perception_responses. Empty answers are retained here but excluded from aggregates. Missing extraction keeps comparison/argued null and comparison_extracted=false. Nested arrays/objects are JSON-encoded in CSV.
share_of_voiceSoV snapshot: brand + competitors, mention counts and shares for the period.
sentimentBrand sentiment: positive/neutral/negative shares among assessed brand mentions. Separate unassessed and not_mentioned rows, plus the share of all non-empty answers and both calculation bases.
brand_perceptionAttribute × entity matrix: attribute, polarity, entity_type/id/name, market_score/rank, entities_ranked, responses_with, attribute_responses, entity_mentions; brand rows also have association_score and terms. association_score is the percentage of eligible brand-mentioning answers with the verified attribute and polarity, including answers without attributes in the denominator. market_score is the percentage of answers with that attribute/polarity that attribute it to this entity. Both count each answer once, independent of descriptor order or brand position. These measure association frequency, not product quality.
presence_summaryPresence counts per group × provider × brand or competitor: total_responses, mentioned_responses, comparison_extracted_responses, leader_count (benchmark), primary_count (primary recommendation), argued_count (conditional choice or concrete reasons), alternative_count (secondary alternative), mention_count (bare mention), absent_count. total_responses includes every non-empty answer to active prompts in that group/provider slice; competitor absent_count = total_responses − mentioned_responses. Competitors appear only in slices where mentioned at least once. If truncated: true, counts cover only the complete answers retained in perception_responses.
perception_responsesOne row per answer × entity: target brand (including absence) and mentioned active competitors. response_id, prompt_id, prompt_text, cluster_id, cluster, created_at, provider_id/name, entity_id/type/name, presence_level (leader/primary/argued/alternative/mention/absent), level_reason, recommendation, comparison (reference/ahead/on_par/behind/none/null), comparison_extracted, argued, sentiment, standing_note (brand only), directly_recommended_entities and directly_recommended_entity_ids, stronger_competitors and stronger_competitor_ids. Brand recommendation preserves citation_type; competitors preserve direct/conditional/other extracted values/null. level_reason: reference = benchmark, directAhead = direct recommendation and ahead, direct = direct recommendation, behind = weaker, negative = negative sentiment, conditional = conditional choice, argued = concrete reasons, rivalDirect = another entity directly recommended, mention = bare mention, absent = absence. Null comparison means missing extraction; none means extracted without a comparison. Caveats are AI wording, not verified facts. stronger_competitors requires brand_comparison=behind and competitor comparison ahead/reference; direct recommendations may name several entities. Uses the same levels as Brand Perception. Non-empty answers to active prompts only, with date/provider/prompt filters. Join responses by response_id and set includeResponseText for the full answer.
competitorsThe brand plus every tracked competitor, brand row first. Reference half: id (same id space as entity_id in competitor_timeline / brand_perception), name, normalized_name, aliases (every spelling mentions are matched by), website, domains, is_active, discovery_source, created_at. Metrics for the export window: mention_count, mention_rate_pct, sov_pct, avg_position, domain_citation_rate_pct. A metric of 0 means measured and never mentioned; null means it could not be computed (see the manifest notes).
providersAI provider catalog (id, slug, name) — for joins with other datasets.
daily_timelineBrand-level metrics per day: responses, mentions, reach %, SoV %, sentiment counts.
competitor_timelinePer-day × per-entity: brand + top-20 competitors per day (long-form). For multi-line charts.
provider_timelinePer-day × per-provider: total_responses, brand_mentions, mention_rate%, sov% per AI provider per day.
positionBrand position: avg_position, top_1_rate%, top_3_rate%, position_4_plus_rate%.
competitive_gapsPrompts where competitors are mentioned but the brand is NOT — priority list of «here you're losing share».
adsAds shown next to AI answers: response_id, prompt_id, ad format and slot, advertiser domain resolved to the brand or a tracked competitor (advertiser_name, advertiser_type), ad title, copy, and landing link. Alice AI only, collected since 5 July 2026 — no backfill. Also includes observation_id, provider_id, prompt_text, group_id, source_group_id, source_ad_id, sitelinks (texts). Observations are detected blocks, not advertising impressions or reach.
ad_groupsAd groups: group_id, advertiser_domain, provider_id/name, ad_type, grouping_basis (order/banner/creative), source_group_id, first_seen, last_seen, observations, days, prompts, variants, banners. Same grouping as AI Ads; source IDs do not prove an advertising-account campaign.
ad_variantsCreative variants within independent groups: group_id, variant_id, advertiser, provider, ad_type, source_group_id/source_ad_id, title, body, target_url, products (JSON string), sitelinks (saved text array), observations, prompts, days.
ad_promptsPrompts per ad group: group_id, advertiser, provider, ad_type, prompt_id/text, observations, days, prompts, variants, first_seen, last_seen.
ad_activityGroup activity by Moscow calendar day: group_id, advertiser, provider, ad_type, date, observations, checks, status (detected/notDetected/notChecked). Not detected is not proof of absence; notChecked means no saved checks.
ad_changesChanges against the adjacent period of equal duration: change_id/type, group_id, advertiser, provider, ad_type, period (current/previous), observations, prompt_id/text, title, current_start/end, previous_start/end, coverage_changed. Types: new_group, new_variant, new_prompt, not_seen, not_checked, new_scope. First detected does not mean campaign launch. No rows without changes; comparison denominators remain available in ad_periods.
ad_periodsComparison denominators: period (current/previous), start_date/end_date, observations, checks, groups, responses_with_ads, observations_per_100_checks (null without checks), checked_prompts, coverage_changed. Identical filters in both periods; coverage differences flagged separately.
shopping_recommendationsCurrent pending, unexpired Alice AI catalog-check recommendations generated over the last 30 days: action_id, status, model/key, observations, first_seen/last_seen, shops, evidence_count, lookback_days. Current tasks, not a historical snapshot. Filters select saved evidence; counts/dates are recomputed from it. Export never triggers paid analysis.
shopping_evidenceRecommendation evidence: action_id, model, response_id, prompt_id/text, created_at, quote, cards (array of title/title_key/shop/shop_key/url). Up to 20 saved answers per recommendation; observations counts selected evidence, not lifetime observations. A missing card does not prove unavailability or guarantee appearance after edits.
ecommerce_cardsOrganic product cards from Alice AI and ChatGPT: response_id, prompt_id, provider_id, created_at, position, title/key, url, shop_name/key, price_text/amount, old_price_amount, currency, rating, review_count, image_url, badge. Date/provider/prompt filters apply. Sponsored galleries are separate in ads; prices are saved observations, not live offers.

Request

Method and URL

POST /api/v1/analytics/export

Body fields

FieldTypeReq.Description
brandIdstring (uuid)✓Brand UUID. Must belong to the token owner.
datasetsstring[]✓Array. Allowed keys: prompts, source_domains, source_pages, responses, share_of_voice, sentiment, brand_perception, competitors, providers, daily_timeline, competitor_timeline, provider_timeline, position, competitive_gaps, ads. At least one. See the dataset catalog below. Also accepts presence_summary and perception_responses. Request each dataset explicitly in the API.
format"csv" | "json"✓csv or json. CSV with >1 dataset returns a zip.
includeResponseTextbooleanOptional. When true and the responses dataset is selected, adds the full AI answer text as response_text and the pre-search answer as memory_response_text. Defaults to false.
includeInactivePromptsbooleanOptional. When true and the prompts dataset is selected, adds deactivated prompts (status = inactive) with their period metrics. Defaults to false — active prompts only.
filters.startDatestring (ISO)✓ISO start timestamp (UTC). Range ≤ 90 days.
filters.endDatestring (ISO)✓ISO end timestamp (UTC).
filters.timeZonestring (IANA)IANA display timezone for dates in filenames; defaults to UTC. Does not shift timestamp filters; ad activity days always use Moscow time.
filters.providerIdsstring[] (uuid)Optional. Provider UUIDs (filter).
filters.promptIdsstring[] (uuid)Optional. Prompt UUIDs (filter).

Example: curl

Replace brandId and token with your own.

curl -X POST https://geoscout.pro/api/v1/analytics/export \
  -H "Authorization: Bearer gs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "00000000-0000-0000-0000-000000000000",
    "datasets": ["prompts", "responses", "brand_perception", "presence_summary", "perception_responses"],
    "format": "csv",
    "includeResponseText": true,
    "filters": {
      "startDate": "2026-04-01T00:00:00Z",
      "endDate": "2026-04-30T23:59:59Z"
    }
  }' -o export.zip

Response

200 OK — file body. Filename in Content-Disposition header (RFC 5987).

Useful headers

  • Content-Type — MIME type: text/csv, application/zip, or application/json
  • Content-Disposition — attachment + UTF-8 filename
  • X-Export-Truncated — Datasets where rows were capped at their row limit (comma-separated keys). Empty = full export.
  • Retry-After — Seconds until rate-limit resets (429 only)

Example: JSON format

{
  "manifest": {
    "exported_at": "2026-05-24T10:15:00.000Z",
    "brand_id": "...",
    "brand_name": "Acme",
    "format": "json",
    "filters": { ... },
    "datasets": ["prompts", "responses"],
    "include_response_text": true,
    "include_inactive_prompts": false,
    "row_counts": { "prompts": 59, "responses": 640 },
    "truncated": {},
    "notes": {
      "responses": "one row per response; join on prompt_id to the prompts dataset for prompt-level metrics"
    }
  },
  "datasets": {
    "prompts": { "rows": [ ... ], "truncated": false },
    "responses": { "rows": [ ... ], "truncated": false }
  }
}

Error codes

CodeHTTPWhen returned
invalid_request400Malformed JSON or Zod validation failed (see detail field)
unauthorized401Token missing, malformed, or unknown
token_expired401Token has expired
token_revoked401Token revoked by owner
insufficient_scope403Token lacks scope mcp:read
forbidden403Brand does not belong to the token owner
rate_limited429Exceeded 10 requests per hour
internal500Internal error. Details in server logs, not in response

Example error response

{
  "error": "rate_limited"
}

Limits

  • —Date range: up to 90 days
  • —Rows per dataset: depends on the dataset (for example, source_pages up to 50,000, responses up to 100,000, or up to 10,000 with the full answer text). Excess data is truncated, see X-Export-Truncated
  • —Rate limit: 10 requests per hour per user (PAT and OAuth tokens of one user share the bucket)
  • —Heavy exports take 10-30s — set client timeout to 60s+