Developer API

REST API экспорта аналитики

Программно выгружайте аналитику бренда из GEO Scout — для BI, кастомных дашбордов и автоматизации.

Что вы получаете

—Аналитику бренда за период до 90 дней одним запросом
—12 датасетов: промпты, источники, ответы AI, Share of Voice, конкуренты, таймлайны и пробелы
—CSV-архив (zip с несколькими файлами) или JSON-bundle
—Те же данные, что и кнопка экспорта в дашборде

Аутентификация

Эндпоинт принимает Bearer-токен. Используются те же токены, что и для MCP-интеграции — Personal Access Token (PAT) или OAuth-токен.

Сгенерировать PAT можно на странице /mcp. Требуется scope mcp:read (выдаётся по умолчанию).

Каталог датасетов

12 датасетов покрывают весь спектр GEO-аналитики — от сырых источников и ответов AI до готовых GEO-метрик и action-oriented срезов. Выбирайте любую комбинацию.

Ключ	Что в нём
prompts	Запросы бренда с per-period метриками: охват, SoV, тональность для каждого промпта.
sources	Цитированные источники long-form: response_id, prompt_id, URL, домен, заголовок страницы, флаги brand/competitor source и атрибуция бренда/конкурентов по каждому источнику. По prompt_id видно, к какому промпту относится источник.
responses	Сырые строки ответов AI: prompt_id, response_id, провайдер, тональность, позиция бренда, тип цитирования. Полный текст ответа добавляется только при includeResponseText: true.
share_of_voice	Снапшот SoV: брэнд + конкуренты, упоминания и доли за период.
sentiment	Snapshot распределения тональности (positive/neutral/negative/not_mentioned), 4 строки.
competitors	Сравнительная таблица бренд+конкуренты с одинаковыми GEO-метриками (reach, SoV, avg position, recommendation rate, citation share).
providers	Каталог AI-провайдеров (id, slug, name) — для join'ов с другими датасетами.
daily_timeline	Бренд-level метрики по дням: ответы, mentions, охват %, SoV %, sentiment counts.
competitor_timeline	Per-day × per-entity: бренд + топ-20 конкурентов по дням (long-form). Для multi-line чартов.
provider_timeline	Per-day × per-provider: total_responses, brand_mentions, mention_rate%, sov% по каждому AI-провайдеру по дням.
position	Позиция бренда: avg_position, top_1_rate%, top_3_rate%, position_4_plus_rate%.
competitive_gaps	Промпты где конкуренты упомянуты, а бренд НЕТ — приоритетный список «здесь теряете долю».

Запрос

Метод и URL

POST /api/v1/analytics/export

Поля запроса

Поле	Тип	Обяз.	Описание
brandId	string (uuid)	✓	UUID бренда. Должен принадлежать владельцу токена.
datasets	string[]	✓	Массив. Допустимые ключи: prompts, sources, responses, share_of_voice, sentiment, competitors, providers, daily_timeline, competitor_timeline, provider_timeline, position, competitive_gaps. Минимум один. См. «Каталог датасетов» ниже.
format	"csv" \| "json"	✓	csv или json. Для csv с >1 датасетом будет возвращён zip.
includeResponseText	boolean		Опционально. Если true и выбран датасет responses, добавляет полный текст ответа AI в колонку response_text. По умолчанию false.
filters.startDate	string (ISO)	✓	ISO-дата начала периода (UTC). Период ≤ 90 дней.
filters.endDate	string (ISO)	✓	ISO-дата конца периода (UTC).
filters.providerIds	string[] (uuid)		Опционально. UUID провайдеров (фильтр).
filters.promptIds	string[] (uuid)		Опционально. UUID промптов (фильтр).

Пример: curl

Замените brandId и токен на свои.

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", "sources", "daily_timeline"],
    "format": "csv",
    "includeResponseText": true,
    "filters": {
      "startDate": "2026-04-01T00:00:00Z",
      "endDate": "2026-04-30T23:59:59Z"
    }
  }' -o export.zip

Ответ

200 OK — тело файла. Файл-имя в заголовке Content-Disposition (RFC 5987).

Полезные заголовки

Content-Type — MIME-тип: text/csv, application/zip или application/json
Content-Disposition — attachment + UTF-8 имя файла
X-Export-Truncated — Список датасетов, где данные были обрезаны своим лимитом строк (CSV-строка ключей). Пусто = всё выгружено целиком.
Retry-After — Секунды до сброса rate-limit (только при 429)

Пример: формат JSON

{
  "manifest": {
    "exported_at": "2026-05-24T10:15:00.000Z",
    "brand_id": "...",
    "brand_name": "Acme",
    "format": "json",
    "filters": { ... },
    "datasets": ["prompts", "responses"],
    "include_response_text": true,
    "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 }
  }
}

Коды ошибок

Код	HTTP	Когда возвращается
invalid_request	400	Невалидный JSON или Zod-валидация не прошла (см. поле detail)
unauthorized	401	Токен отсутствует, неверного формата или не найден
token_expired	401	Срок действия токена истёк
token_revoked	401	Токен отозван владельцем
insufficient_scope	403	Токен не имеет scope mcp:read
forbidden	403	Бренд не принадлежит владельцу токена
rate_limited	429	Превышен лимит 10 запросов в час
internal	500	Внутренняя ошибка. Подробности в логах сервера, не в ответе

Пример ответа на ошибку

{
  "error": "rate_limited"
}

Лимиты

—Период экспорта: до 90 дней
—Строк на датасет: зависит от датасета (например, sources до 100 000, responses до 10 000). Превышение → данные обрезаны, см. X-Export-Truncated
—Rate-limit: 10 запросов в час на пользователя (PAT и OAuth-токены одного юзера разделяют квоту)
—Тяжёлые экспорты могут занять 10-30 секунд — таймаут клиента ставьте от 60 секунд