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

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

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

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

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

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

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

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

Запрос

Метод и URL

Поля запроса

Пример: 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", "source_domains", "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 }
  }
}

Коды ошибок

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

{
  "error": "rate_limited"
}

Лимиты

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