> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# SEO API

> Данные по ключевым словам, позиции домена, обратные ссылки, Domain Rating и трафик сайта с одним ключом BeatAPI. Двенадцать инструментов возвращают результат прямо в ответе, для приложений и агентов.

Двенадцать инструментов дают приложению или агенту данные для SEO: сколько ищут ключевое слово и насколько трудно по нему подняться, какие слова и страницы приносят домену поисковый трафик, кто с ним конкурирует, кто на него ссылается, каков его Domain Rating и сколько посещений у сайта. Каждый инструмент — это один `POST` в `/v1/seo/` с вашим API-ключом BeatAPI и результатом в одном ответе. Агентам те же инструменты доступны как [возможности](#agents).

## Быстрый старт

```bash
curl https://api.beatapi.io/v1/seo/keyword-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis cluster"],"country":"us"}'
```

```json
{
  "object": "seo.keyword_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "monthly_searches": [{ "year": 2026, "month": 9, "search_volume": 590 }]
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

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

Передавайте ключ BeatAPI API при каждом вызове как `Authorization: Bearer <key>`; ключ работает и с префиксом `sk-`, и без него. Создать ключ можно в разделе [Панель → API Keys](https://beatapi.io/dashboard/apikeys). Все инструменты доступны на `https://api.beatapi.io` и списывают средства с баланса аккаунта.

## Выбор инструмента

| Что нужно                                                                    | Инструмент           |
| ---------------------------------------------------------------------------- | -------------------- |
| Объём поиска, CPC, сложность, интент и история по месяцам для известных слов | `keyword-overview`   |
| Новые ключевые слова по теме                                                 | `keyword-ideas`      |
| Только сложность списка слов                                                 | `keyword-difficulty` |
| Поисковое присутствие домена на одном рынке                                  | `domain-overview`    |
| Слова, по которым домен занимает позиции, или его позиция по одному слову    | `ranked-keywords`    |
| Страницы домена по поисковому трафику                                        | `top-pages`          |
| Домены, конкурирующие за те же слова                                         | `competitors`        |
| Ссылочный профиль домена в цифрах                                            | `backlink-summary`   |
| Сами ссылки                                                                  | `backlinks`          |

О Domain Rating и общем числе посещений сайта рассказано в разделе [Domain Rating и трафик сайта](#domain-rating-and-site-traffic).

Инструмента живой поисковой выдачи нет. Чтобы проверить позицию домена по слову, вызовите `ranked-keywords` с `contains`. Это последняя зафиксированная позиция, а не текущая.

## Страна и язык

`country` и `language` выбирают рынок: поиск Google в этой стране на этом языке. Их принимают инструменты для ключевых слов, а также `domain-overview`, `ranked-keywords`, `top-pages` и `competitors`. У инструментов для обратных ссылок рынка нет, и оба поля отклоняются.

| Поле       | По умолчанию        | Правило                                                                                                                        |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `country`  | `us`                | Двухбуквенный код в нижнем регистре, например `us`, `gb`, `de` или `jp`. Доступно около 90 рынков. Китая (`cn`) среди них нет. |
| `language` | Основной язык рынка | Один из языков рынка, например `es` для `us`, `fr` для `ca` или `zh-TW` для `hk`.                                              |

Страна или язык вне списка отклоняются с `400 bad_request`, а сообщение подсказывает, что есть на этом рынке: `language 'de' is not covered in us; use one of: en, es`.

## Лимит и смещение

`keyword-ideas`, `ranked-keywords`, `top-pages`, `competitors` и `backlinks` возвращают строки постранично.

| Поле     | По умолчанию | Диапазон                                                                                                            |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `limit`  | `100`        | 1–1000 строк, 1–999 для `competitors`. Оплачивается каждая возвращённая строка, поэтому запрашивайте только нужное. |
| `offset` | `0`          | Сколько строк пропустить: 0–10000. Для следующей страницы прибавьте `limit` к этому значению.                       |

Эти ответы повторяют `limit` и `offset`, а также содержат `total` — общее число доступных строк, если оно известно.

## Ответы

Все инструменты отвечают синхронно: результат приходит в ответе на ваш `POST`, опрашивать нечего. Большинство вызовов занимает несколько секунд.

| Поле                  | Описание                                                                                                                                                               |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`              | Инструмент, например `seo.ranked_keywords`.                                                                                                                            |
| `request_id`          | Указывайте в обращениях в поддержку. `GET /v1/tasks/{id}` с этим id возвращает тот же результат в `output`, поэтому потерянный ответ не означает потерянный результат. |
| `country`, `language` | Использованный рынок, если инструмент его принимает.                                                                                                                   |
| `domain`              | Использованный домен, если инструмент его принимает. Полный URL сокращается до домена, начальный `www.` отбрасывается.                                                 |
| `results[]`           | Строки, если инструмент возвращает список. Другие инструменты выводят поля на верхний уровень.                                                                         |
| `billed_rows`         | Строки, за которые списана оплата этого вызова.                                                                                                                        |
| `has_data`            | Есть у `domain-overview`, `backlink-summary` и инструментов Domain Rating и трафика сайта. `false` означает, что домена нет в данных.                                  |
| `usage`               | Завершает каждый ответ: сколько стоил вызов.                                                                                                                           |

`usage.price_usd` — итоговое списание в долларах США. `billing_unit` всегда равно `request`, а `quantity` всегда равно `1`; `billed_rows` показывает, сколько строк покрывает это списание.

Числа, которых нет в данных, в строку не попадают, поэтому перед использованием проверяйте наличие поля. Неизвестные поля запроса отклоняются с `400 bad_request`: если бы поле с опечаткой молча игнорировалось, вы получили бы ответ на другой вопрос.

## Инструменты для ключевых слов

### Обзор ключевых слов

`POST https://api.beatapi.io/v1/seo/keyword-overview`

Объём поиска, CPC, конкуренция, сложность, интент и история по месяцам для известных слов. Слово, которое никто не ищет, в ответ не попадает и нулём не отмечается.

| Поле       | Тип       | Обязательно | Описание                                                                                                           |
| ---------- | --------- | ----------: | ------------------------------------------------------------------------------------------------------------------ |
| `keywords` | string\[] |          Да | 1–100 ключевых слов длиной до 80 символов каждое. Они приводятся к нижнему регистру, повторы учитываются один раз. |
| `country`  | string    |         Нет | См. раздел [Страна и язык](#country-and-language).                                                                 |
| `language` | string    |         Нет | См. раздел [Страна и язык](#country-and-language).                                                                 |

Ответ показан в разделе [Быстрый старт](#quick-start). Поля каждой строки:

| Поле                 | Описание                                                                        |
| -------------------- | ------------------------------------------------------------------------------- |
| `keyword`            | Ключевое слово.                                                                 |
| `search_volume`      | Число поисков в месяц на этом рынке.                                            |
| `cpc_usd`            | Стоимость клика в платной рекламе, в долларах США.                              |
| `competition`        | Конкуренция рекламодателей, от 0 до 1.                                          |
| `keyword_difficulty` | Насколько трудно занять позицию по этому слову, от 0 до 100.                    |
| `intent`             | Основной поисковый интент, например `informational` или `navigational`.         |
| `updated_at`         | Когда данные по этому слову обновлялись в последний раз.                        |
| `monthly_searches[]` | `year`, `month` и `search_volume` за каждый месяц. Только в `keyword-overview`. |

### Идеи ключевых слов

`POST https://api.beatapi.io/v1/seo/keyword-ideas`

Связанные слова для ваших исходных слов, сначала самые релевантные. Поля строк те же, что в `keyword-overview`, но без `monthly_searches`.

| Поле                  | Тип       | Обязательно | Описание                                           |
| --------------------- | --------- | ----------: | -------------------------------------------------- |
| `keywords`            | string\[] |          Да | 1–20 исходных слов длиной до 80 символов каждое.   |
| `limit`, `offset`     | integer   |         Нет | См. раздел [Лимит и смещение](#limit-and-offset).  |
| `country`, `language` | string    |         Нет | См. раздел [Страна и язык](#country-and-language). |

```bash
curl https://api.beatapi.io/v1/seo/keyword-ideas \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis sentinel"],"limit":20}'
```

### Сложность ключевых слов

`POST https://api.beatapi.io/v1/seo/keyword-difficulty`

Только `keyword_difficulty`, сразу для многих слов. Поля те же, что в `keyword-overview`.

```json
{
  "object": "seo.keyword_difficulty",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    { "keyword": "redis cluster", "keyword_difficulty": 15 },
    { "keyword": "redis sentinel", "keyword_difficulty": 2 }
  ],
  "billed_rows": 2,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0186",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

## Инструменты для доменов

Все четыре принимают `domain`, например `example.com`, а также `country` и `language`.

### Обзор домена

`POST https://api.beatapi.io/v1/seo/domain-overview`

Органическое и платное поисковое присутствие домена на одном рынке. Это только поисковый трафик, а не все посещения сайта.

```bash
curl https://api.beatapi.io/v1/seo/domain-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","country":"us"}'
```

```json
{
  "object": "seo.domain_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "has_data": true,
  "organic": {
    "ranking_keywords": 22125,
    "search_traffic_estimate": 108626.58,
    "traffic_value_usd_estimate": 483101.98,
    "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
    "new": 18919,
    "up": 1048,
    "down": 1105,
    "lost": 4041
  },
  "paid": { "ranking_keywords": 0, "search_traffic_estimate": 0 },
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| Поле                         | Описание                                                                           |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `ranking_keywords`           | Число ключевых слов с позициями на этом рынке.                                     |
| `search_traffic_estimate`    | Оценка поискового трафика в месяц.                                                 |
| `traffic_value_usd_estimate` | Оценка стоимости такого трафика при покупке рекламы, в долларах США.               |
| `rank_distribution`          | Число слов по диапазонам позиций: `1`, `2-3`, `4-10`, `11-20`, `21-30` и `31-100`. |
| `new`, `up`, `down`, `lost`  | Слова, по которым позиции недавно появились, выросли, упали или потеряны.          |

Домен, которого нет в данных, возвращается с `has_data: false` и без `organic` и `paid`. Это отсутствие данных, а не нулевой трафик, и вызов оплачивается.

### Ключевые слова домена

`POST https://api.beatapi.io/v1/seo/ranked-keywords`

Слова, по которым домен занимает позиции на одном рынке, сначала с наибольшим объёмом поиска.

| Поле                  | Тип     | Обязательно | Описание                                                                                |
| --------------------- | ------- | ----------: | --------------------------------------------------------------------------------------- |
| `domain`              | string  |          Да | Домен.                                                                                  |
| `contains`            | string  |         Нет | Только слова с этим текстом, до 80 символов, без учёта регистра. `%` и `_` отклоняются. |
| `limit`, `offset`     | integer |         Нет | См. раздел [Лимит и смещение](#limit-and-offset).                                       |
| `country`, `language` | string  |         Нет | См. раздел [Страна и язык](#country-and-language).                                      |

```bash
curl https://api.beatapi.io/v1/seo/ranked-keywords \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","contains":"cluster","limit":1}'
```

```json
{
  "object": "seo.ranked_keywords",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 108,
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "position": 1,
      "absolute_position": 2,
      "url": "https://redis.io/docs/cluster/",
      "title": "Redis cluster",
      "position_seen_at": "2026-09-14 04:53:47 +00:00",
      "search_traffic_estimate": 12.35
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

К полям `keyword-ideas` строки добавляют:

| Поле                      | Описание                                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `position`                | Позиция среди органических результатов.                                                            |
| `absolute_position`       | Позиция с учётом всех элементов страницы результатов.                                              |
| `url`, `title`            | Страница, занимающая эту позицию.                                                                  |
| `position_seen_at`        | Когда зафиксирована эта позиция. Позиции — это снимок, им может быть несколько недель или месяцев. |
| `search_traffic_estimate` | Оценка месячного поискового трафика, который это слово приносит странице.                          |

### Топ страниц

`POST https://api.beatapi.io/v1/seo/top-pages`

Страницы домена, сначала с наибольшей оценкой поискового трафика. Поля: `domain`, `limit`, `offset`, `country`, `language`. В каждой строке есть `url` и [поля поискового присутствия](#domain-overview) этой страницы.

```json
{
  "object": "seo.top_pages",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 1104,
  "results": [
    {
      "url": "https://redis.io/",
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58,
      "traffic_value_usd_estimate": 483101.98,
      "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
      "new": 18919,
      "up": 1048,
      "down": 1105,
      "lost": 4041
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

### Конкуренты

`POST https://api.beatapi.io/v1/seo/competitors`

Домены, конкурирующие с указанным за те же поисковые запросы. Поля: `domain`, `limit`, `offset`, `country`, `language`. Сам домен и крупнейшие сайты общего назначения, такие как youtube.com и wikipedia.org, в строки не входят, а `total` считает только оставшиеся.

```json
{
  "object": "seo.competitors",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 9,
  "results": [
    {
      "domain": "example.com",
      "shared_keywords": 4706,
      "avg_position": 29.6,
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| Поле                      | Описание                                             |
| ------------------------- | ---------------------------------------------------- |
| `domain`                  | Домен-конкурент.                                     |
| `shared_keywords`         | Число слов, по которым позиции есть у обоих доменов. |
| `avg_position`            | Его средняя позиция по этим словам.                  |
| `ranking_keywords`        | Всего слов, по которым он занимает позиции.          |
| `search_traffic_estimate` | Оценка его поискового трафика в месяц.               |

## Инструменты для обратных ссылок

### Сводка по ссылкам

`POST https://api.beatapi.io/v1/seo/backlink-summary`

Ссылочный профиль домена. Единственное поле — `domain`.

```json
{
  "object": "seo.backlink_summary",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "link_authority": 500,
  "backlinks": 920428,
  "referring_domains": 32647,
  "referring_main_domains": 28596,
  "referring_pages": 748383,
  "referring_ips": 19191,
  "broken_backlinks": 8482,
  "broken_pages": 2773,
  "spam_score": 28,
  "first_seen": "2019-01-15 22:56:44 +00:00",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| Поле                                          | Описание                                                                                  |
| --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `link_authority`                              | Авторитетность ссылочного профиля: от 0 до 1000 по собственной шкале этого набора данных. |
| `backlinks`                                   | Найдено ссылок.                                                                           |
| `referring_domains`, `referring_main_domains` | Домены, ссылающиеся на него, и то же число, где поддомены считаются за один.              |
| `referring_pages`, `referring_ips`            | Страницы и IP-адреса, ссылающиеся на него.                                                |
| `broken_backlinks`, `broken_pages`            | Битые ссылки и страницы домена, которые больше не открываются.                            |
| `spam_score`                                  | Оценка спама для профиля. Чем она выше, тем вероятнее спам.                               |
| `first_seen`                                  | Когда ссылка на домен была замечена впервые.                                              |

Если домена нет в данных, `has_data` равно `false`, других полей нет, и вызов оплачивается.

### Обратные ссылки

`POST https://api.beatapi.io/v1/seo/backlinks`

Ссылки на домен, сначала самые сильные.

| Поле              | Тип     | Обязательно | Описание                                                                                           |
| ----------------- | ------- | ----------: | -------------------------------------------------------------------------------------------------- |
| `domain`          | string  |          Да | Домен.                                                                                             |
| `one_per_domain`  | boolean |         Нет | По умолчанию `true`: по одной ссылке с каждого домена. Задайте `false`, чтобы получить все ссылки. |
| `limit`, `offset` | integer |         Нет | См. раздел [Лимит и смещение](#limit-and-offset).                                                  |

```json
{
  "object": "seo.backlinks",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 28843,
  "results": [
    {
      "source_url": "https://blog.example.com/caching",
      "source_domain": "blog.example.com",
      "source_title": "Caching notes",
      "source_authority": 493,
      "source_country": "CZ",
      "target_url": "https://redis.io/",
      "anchor": "Redis",
      "link_type": "anchor",
      "dofollow": true,
      "spam_score": 3,
      "first_seen": "2025-04-26 07:12:33 +00:00",
      "last_seen": "2026-06-18 19:14:30 +00:00",
      "is_new": false,
      "is_lost": false,
      "is_broken": false
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| Поле                                          | Описание                                                             |
| --------------------------------------------- | -------------------------------------------------------------------- |
| `source_url`, `source_domain`, `source_title` | Страница со ссылкой.                                                 |
| `source_authority`                            | Авторитетность ссылочного профиля ссылающегося домена, от 0 до 1000. |
| `source_country`                              | Страна ссылающегося домена.                                          |
| `target_url`, `anchor`                        | Страница, на которую ведёт ссылка, и текст ссылки.                   |
| `link_type`                                   | Вид ссылки, например `anchor`.                                       |
| `dofollow`                                    | Передаёт ли ссылка вес.                                              |
| `spam_score`                                  | Оценка спама для этой ссылки. Чем она выше, тем вероятнее спам.      |
| `first_seen`, `last_seen`                     | Когда ссылка была замечена впервые и в последний раз.                |
| `is_new`, `is_lost`, `is_broken`              | Ссылка новая, исчезла или битая.                                     |

## Как читать цифры

* **Поисковый трафик.** `search_traffic_estimate` — это оценка поискового трафика, а не всех посещений сайта.
* **Оценки.** Цифры трафика и его стоимости — это оценки, а не измерения сайта.
* **Link authority.** `link_authority` измеряется от 0 до 1000 по собственной шкале этого набора данных.
* **Сложность ключевых слов** — собственная шкала этого набора данных. Не сравнивайте её с оценками других инструментов.
* **Нет значения — не ноль.** Отсутствующее число означает «неизвестно» и никогда не означает ноль.
* **Живой выдачи нет.** Инструмента живой поисковой выдачи нет. Чтобы проверить позицию домена по слову, используйте [`ranked-keywords`](#ranked-keywords) с `contains`. Это последняя зафиксированная позиция, а не текущая.
* **Для Domain Rating и трафика сайта** есть отдельные пояснения в разделе [Как читать эти цифры](#reading-these-numbers).

## Оплата

| Инструмент                                                                                                                  | За вызов | За возвращённую строку |
| --------------------------------------------------------------------------------------------------------------------------- | -------: | ---------------------: |
| `keyword-overview`, `keyword-ideas`, `keyword-difficulty`, `domain-overview`, `ranked-keywords`, `top-pages`, `competitors` |  \$0.018 |               \$0.0003 |
| `backlink-summary`, `backlinks`                                                                                             |  \$0.035 |               \$0.0002 |

У Domain Rating и трафика сайта [свои цены](#prices-of-these-tools).

* `domain-overview` и `backlink-summary` возвращают одну запись, она считается одной строкой, а при `has_data`, равном `false`, строк нет. Вызов `ranked-keywords`, вернувший 100 строк, стоит \$0.048.
* Вызов без результатов всё равно стоит цены за вызов. Отклонённый запрос (`400`) и неудачный вызов (`503`) не оплачиваются.
* Перед вызовом на балансе должно хватать средств на максимальную стоимость: все строки `limit` или все отправленные слова. Затем оплата списывается только за то, что вернулось.
* Если клиент может повторить тот же запрос, передайте заголовок `Idempotency-Key`. Повтор ключа с другим телом запроса отклоняется с `409 idempotency_conflict`.

## Агенты

Отдельного инструмента MCP для SEO-данных нет. На MCP-сервере BeatAPI `https://beatapi.io/mcp` агенты используют `capabilities_search`, `capabilities_inspect` и `capabilities_run` с такими ссылками:

| Ссылка                        | Инструмент           |
| ----------------------------- | -------------------- |
| `data:seo.keyword_overview`   | `keyword-overview`   |
| `data:seo.keyword_ideas`      | `keyword-ideas`      |
| `data:seo.keyword_difficulty` | `keyword-difficulty` |
| `data:seo.domain_overview`    | `domain-overview`    |
| `data:seo.ranked_keywords`    | `ranked-keywords`    |
| `data:seo.top_pages`          | `top-pages`          |
| `data:seo.competitors`        | `competitors`        |
| `data:seo.backlink_summary`   | `backlink-summary`   |
| `data:seo.backlinks`          | `backlinks`          |

Ссылки для Domain Rating и трафика сайта [приведены рядом с этими инструментами](#references-for-agents).

Inspect показывает схему ввода и текущую цену. `input` — это тело запроса инструмента, а Run возвращает результат:

```json
{ "reference": "data:seo.ranked_keywords", "operation": "start", "input": { "domain": "redis.io", "contains": "cluster", "limit": 20 } }
```

Те же три вызова доступны через REST: `POST /v1/capabilities/search`, `/v1/capabilities/inspect` и `/v1/capabilities/run`. См. [API возможностей](/capabilities).

## Ошибки

Ошибки используют стандартный объект ошибки BeatAPI с `retryable` в каждом ответе. Правила повторов приведены в разделе [ошибок](/errors).

```json
{
  "error": {
    "code": "bad_request",
    "message": "country 'cn' is not covered; use a two-letter code such as us, gb, de or jp (China is not covered)",
    "retryable": false,
    "request_id": "req_abc123"
  }
}
```

| HTTP-статус | Код                                                                    | Значение                                                                                                               |
| ----------: | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|         400 | `bad_request`                                                          | Неверное или неизвестное поле, недопустимое ключевое слово или домен либо рынок вне покрытия. Сообщение называет поле. |
|         401 | `missing_api_key` / `invalid_api_key`                                  | Ключ отсутствует, неверен, просрочен, отключён или его лимит исчерпан.                                                 |
|         402 | `insufficient_credits`                                                 | Баланс равен нулю или меньше стоимости вызова.                                                                         |
|         403 | `forbidden`                                                            | Ключу или аккаунту запрещён этот вызов.                                                                                |
|         409 | `idempotency_conflict`                                                 | `Idempotency-Key` повторно использован с другим телом запроса.                                                         |
|         429 | `rate_limit_exceeded`                                                  | Слишком много запросов. Подождите `retry_after_seconds`.                                                               |
|         500 | `internal_error`                                                       | Непредвиденная внутренняя ошибка. Повтор допустим.                                                                     |
|         503 | `processing_unavailable`, `processing_timeout` или `processing_failed` | SEO-данные временно недоступны либо вызов занял слишком много времени. Повторите с нарастающей паузой.                 |

Ответ `503` никогда не оплачивается. BeatAPI не возвращает `502`.

## Domain Rating и трафик сайта

Ещё три инструмента работают так же: тот же ключ, тот же результат в ответе, те же `usage` и ошибки. Они принимают `domain` и не имеют рынка, поэтому `country` и `language` отклоняются. Полей `limit` и `offset` нет.

| Что нужно                                                    | Инструмент              |
| ------------------------------------------------------------ | ----------------------- |
| Оценка от 0 до 100, по которой SEO-команды сравнивают домены | `domain-rating`         |
| Та же оценка по месяцам                                      | `domain-rating-history` |
| Все посещения сайта, их источники и поведение посетителей    | `site-traffic`          |

### Domain Rating

`POST https://api.beatapi.io/v1/seo/domain-rating`

```bash
curl https://api.beatapi.io/v1/seo/domain-rating \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io"}'
```

```json
{
  "object": "seo.domain_rating",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "domain_rating": 90,
  "link_rank": 1927,
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

`domain_rating` измеряется от 0 до 100. `link_rank` — мировой рейтинг домена по ссылкам; чем меньше значение, тем сильнее домен.

### История Domain Rating

`POST https://api.beatapi.io/v1/seo/domain-rating-history`

```json
{
  "object": "seo.domain_rating_history",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "results": [
    { "month": "2025-12", "domain_rating": 89 },
    { "month": "2026-01", "domain_rating": 89 },
    { "month": "2026-02", "domain_rating": 89 },
    { "month": "2026-03", "domain_rating": 89 },
    { "month": "2026-04", "domain_rating": 89 },
    { "month": "2026-05", "domain_rating": 89 },
    { "month": "2026-06", "domain_rating": 90 },
    { "month": "2026-07", "domain_rating": 90 },
    { "month": "2026-08", "domain_rating": 90 },
    { "month": "2026-09", "domain_rating": 90 },
    { "month": "2026-10", "domain_rating": 90 }
  ],
  "billed_rows": 11,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.044",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

Для неизвестного домена возвращаются `has_data: false`, пустой `results` и `billed_rows: 1`.

### Трафик сайта

`POST https://api.beatapi.io/v1/seo/site-traffic`

Оценка всех посещений сайта из всех каналов, а также источники, страны, рейтинг и вовлечённость.

| Поле     | Тип     | Обязательно | Описание                                                     |
| -------- | ------- | ----------: | ------------------------------------------------------------ |
| `domain` | string  |          Да | Домен.                                                       |
| `months` | integer |         Нет | Глубина истории в месяцах: `3` (по умолчанию), `6` или `12`. |

```bash
curl https://api.beatapi.io/v1/seo/site-traffic \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","months":3}'
```

```json
{
  "object": "seo.site_traffic",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "months": 3,
  "has_data": true,
  "site_visits_estimate": 734682,
  "monthly_visits": [
    { "month": "2026-07", "visits": 827501 },
    { "month": "2026-08", "visits": 789909 },
    { "month": "2026-09", "visits": 734682 }
  ],
  "global_rank": 66213,
  "country_rank": { "country": "IN", "rank": 19016 },
  "category": "computers_electronics_and_technology/programming_and_developer_software",
  "category_rank": 634,
  "bounce_rate": 0.4254,
  "pages_per_visit": 3.3174,
  "avg_visit_seconds": 116.2764,
  "traffic_sources": {
    "direct": 0.3293,
    "search": 0.4836,
    "paid_search": 0.0072,
    "social": 0.0435,
    "paid_social": 0.0026,
    "referrals": 0.0992,
    "mail": 0.0114,
    "display_ads": 0.0035,
    "affiliate": 0,
    "gen_ai": 0.0197
  },
  "top_countries": [{ "country": "IN", "share": 0.1995 }],
  "top_keywords": [{ "keyword": "redis", "search_volume": 193980, "cpc_usd": 2.78 }],
  "title": "Redis - Real-time data for agents & apps",
  "description": "Developers love Redis. Unlock the full potential of the Redis database with Redis Enterprise and start building blazing fast apps.",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| Поле                                   | Описание                                                              |
| -------------------------------------- | --------------------------------------------------------------------- |
| `site_visits_estimate`                 | Оценка посещений за последний месяц.                                  |
| `monthly_visits[]`                     | `month` и `visits` за каждый месяц.                                   |
| `global_rank`                          | Место среди всех сайтов. Чем меньше значение, тем крупнее сайт.       |
| `country_rank`                         | Место в одной стране: `country` и `rank`.                             |
| `category`, `category_rank`            | Категория сайта и его место в ней.                                    |
| `bounce_rate`                          | Доля посещений, завершившихся после одной страницы, от 0 до 1.        |
| `pages_per_visit`, `avg_visit_seconds` | Страниц за посещение и средняя длительность посещения в секундах.     |
| `traffic_sources`                      | Доля посещений из каждого канала, от 0 до 1.                          |
| `top_countries[]`                      | Страны с наибольшим числом посещений, у каждой `share` от 0 до 1.     |
| `top_keywords[]`                       | Слова, приносящие посещения из поиска, с `search_volume` и `cpc_usd`. |
| `title`, `description`                 | Собственные заголовок и описание сайта.                               |

### Как читать эти цифры

* **Два вида трафика.** `search_traffic_estimate` — оценка поискового трафика; `site_visits_estimate` — все посещения из всех каналов. Это разные показатели: никогда не складывайте и не сравнивайте их. Посещения — это не уникальные посетители.
* **Две оценки авторитетности.** `link_authority` измеряется от 0 до 1000 по собственной шкале этого набора данных; `domain_rating` — от 0 до 100. Пересчитать одно в другое нельзя.
* **Нет в данных.** `has_data: false` означает, что домена нет в данных; это не то же самое, что нулевой рейтинг или трафик: у нового сайта рейтинг может быть `0`, а `link_rank` при этом есть.

### Цены этих инструментов

| Инструмент                 |                          Цена |
| -------------------------- | ----------------------------: |
| `domain-rating`            |              \$0.005 за вызов |
| `domain-rating-history`    | \$0.004 за возвращённый месяц |
| `site-traffic`, 3 месяца   |                       \$0.005 |
| `site-traffic`, 6 месяцев  |                        \$0.01 |
| `site-traffic`, 12 месяцев |                       \$0.015 |

* `domain-rating` и `site-traffic` оплачиваются и при `has_data`, равном `false`. `domain-rating-history` для неизвестного домена не возвращает месяцев и стоит как один месяц, \$0.004.
* Отклонённый запрос (`400`) и неудачный вызов (`503`) не оплачиваются.
* Перед вызовом `domain-rating-history` на балансе должно хватать средств на 24 месяца истории. Затем оплата списывается только за то, что вернулось.

### Ссылки для агентов

| Ссылка                           | Инструмент              |
| -------------------------------- | ----------------------- |
| `data:seo.domain_rating`         | `domain-rating`         |
| `data:seo.domain_rating_history` | `domain-rating-history` |
| `data:seo.site_traffic`          | `site-traffic`          |