---
name: spytay
description: Вимірювання видимості бренду у відповідях ChatGPT, Gemini, Claude і Grok: як замовити перший звіт Spytay і як читати свої звіти через REST API та MCP (лише читання).
version: 1.0.0
---

# Spytay

## Що це

Spytay вимірює, чи називають асистенти (ChatGPT та інші) ваш бренд у відповідях про вашу категорію. Через цей доступ агент лише читає звіти, які вже замовлено, нічого не замовляє й не змінює.

Як читати числа:

- `visibility` — частка відповідей, де асистент назвав бренд (від 0 до 1); `lo` і `hi` — межі інтервалу.
- `first_place` — частка відповідей, де бренд названо першим; `mean_rank` — середнє місце, коли названо.
- `n` — скільки відповідей враховано; `k` — скільки брендів асистент називає в одній відповіді.

## Якщо ви ще не клієнт

Людина попросила вас налаштувати Spytay, а звітів у неї ще немає. Допоможіть їй замовити перший.

1. Поясніть, що ми робимо: ставимо ChatGPT, Gemini, Claude і Grok ті самі запитання, що й покупці, до 20 разів кожне, і рахуємо, як часто асистенти називають її бренд і конкурентів. Кожне число — з діапазоном 95 %.
2. Допоможіть обрати пакет:
   - «Звіт» — $69 разово: одне вимірювання і план дій з 3–6 кроків.
   - «Моніторинг щомісяця» — $49/міс: те саме вимірювання щомісяця і динаміка.
   - «Автопілот» — $299/міс: вимірювання щомісяця і Набір матеріалів для сайту (FAQ, schema.org, llms.txt).
3. Підготуйте з нею дані для замовлення — вона вставить їх після оплати:
   - категорія — як її шукають покупці, до 120 символів: «сухий корм для котів», «стоматологія у Львові»;
   - назва бренду — до 80 символів, так, як її пишуть покупці;
   - до восьми конкурентів; можна без них — асистенти самі покажуть, кого радять;
   - для пакета «Автопілот» ще адреса сайту (https://…) і мета на найближчі місяці, до 1 500 символів.
4. Дайте посилання на оплату обраного пакета:
   - https://spytay.com/order?package=report
   - https://spytay.com/order?package=monitoring
   - https://spytay.com/order?package=actions
   Оплачує людина сама, карткою на сторінці Creem. Не вводьте дані картки замість неї.
5. Після оплати відкриється сторінка замовлення; посилання на неї також прийде на пошту. Людина вставляє дані й погоджується на старт. Після цього дані змінити не можна, тож перевірте написання бренду й категорії. Звіт зазвичай готовий за кілька хвилин, перший Набір для пакета «Автопілот» — зазвичай протягом години.
6. Коли звіт готовий, підключіть доступ до нього: розділи «Ключ», «API» і «MCP» нижче.

## Ключ

1. Відкрийте кабінет: https://spytay.com/a/api.
2. Натисніть «Створити ключ» і скопіюйте його одразу: показуємо лише один раз. Ключ має вигляд `spk_…`.
3. Вставте ключ у налаштування свого агента (див. нижче) або в змінну середовища `SPYTAY_API_KEY`.

## API

Адреса: `https://spytay.com/api/v1`. Кожен запит має заголовок `Authorization: Bearer <KEY>`. Повний опис: https://spytay.com/api/v1/docs, специфікація OpenAPI 3.1: https://spytay.com/api/v1/openapi.json.

```
curl -H "Authorization: Bearer $SPYTAY_API_KEY" "https://spytay.com/api/v1/me"
curl -H "Authorization: Bearer $SPYTAY_API_KEY" "https://spytay.com/api/v1/reports"
curl -H "Authorization: Bearer $SPYTAY_API_KEY" "https://spytay.com/api/v1/reports/41"
curl -H "Authorization: Bearer $SPYTAY_API_KEY" "https://spytay.com/api/v1/reports/41/answers?assistant=openai/gpt-5.5&page=1"
curl -H "Authorization: Bearer $SPYTAY_API_KEY" "https://spytay.com/api/v1/reports/41/plan"
```

- `/me` — чий це ключ і які ліміти.
- `/reports` — ваші звіти (`limit`, `offset`).
- `/reports/{id}` — висновок, місце серед брендів, таблиці за асистентами та умовами запитів.
- `/reports/{id}/answers` — відповіді асистентів дослівно (`assistant`, `condition`, `mentions`, `page`, `page_size`). Те саме файлом CSV: `/reports/{id}/answers.csv`.
- `/reports/{id}/plan` — дії та дата наступного вимірювання.

## MCP

Віддалений сервер: `https://spytay.com/mcp` (Streamable HTTP, лише читання). Підставте свій ключ замість `<KEY>`.

Claude Code:

```
claude mcp add --transport http spytay https://spytay.com/mcp --header "Authorization: Bearer <KEY>"
```

Cursor, файл `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "spytay": {
      "url": "https://spytay.com/mcp",
      "headers": {
        "Authorization": "Bearer <KEY>"
      }
    }
  }
}
```

Hermes, розділ `mcp_servers` у конфігурації:

```yaml
mcp_servers:
  spytay:
    url: "https://spytay.com/mcp"
    headers:
      Authorization: "Bearer <KEY>"
```

Інструменти:

- `list_reports` (`limit`) — список ваших звітів.
- `get_report` (`report_id`) — повний звіт: висновок, місце, таблиці, пояснення.
- `get_answers` (`report_id`, `assistant`, `condition`, `mentions`, `page`, `page_size`) — відповіді асистентів дослівно, сторінками.
- `get_plan` (`report_id`) — дії та дата наступного вимірювання.

Результат — той самий JSON, що повертає REST API. Помилка — `isError: true` і той самий об'єкт `{"error": {"code", "message"}}`, що в REST.

## Правила

- Доступ лише для читання: нічого не замовляється й не змінюється.
- Ліміти: 60 запитів за хвилину і 1 000 за годину на ключ. Після відповіді 429 зачекайте стільки секунд, скільки вказано в заголовку `Retry-After`.
- Не вставляйте ключ у чати, листи чи публічні репозиторії. Якщо ключ потрапив не туди, відкличте його в https://spytay.com/a/api і створіть новий.
- Чужі звіти недоступні: запит повертає 404.

## Помилки

Помилка завжди приходить як JSON: `{"error": {"code": "...", "message": "..."}}`.

- `unauthorized` (401) — немає ключа або він відкликаний.
- `not_found` (404) — звіту немає або він не ваш.
- `validation_error` (422) — некоректний параметр.
- `rate_limited` (429) — перевищено ліміт, дивіться `Retry-After`.
- `internal_error` (500) — спробуйте пізніше.

Умови сервісу: https://spytay.com/offer, конфіденційність: https://spytay.com/privacy.