> 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.

# Social Data API

BeatAPI Social Data — синхронный API для разработчиков, получающий общедоступные данные поддерживаемых соцсетей. Вы используете API-ключ BeatAPI и ID действия BeatAPI. Учётные записи, маршрутизация и внутренние данные ответов скрыты за API.

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

Выберите действие в [каталоге Social Data](/social-data-catalog), затем передайте его ID и параметры:

```bash
curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"douyin.web.fetch_one_video","params":{"aweme_id":"7364837462110"}}'
```

Публичный метод — `POST /v1/social-data/call`. Поле `model` для него не требуется: операцию определяет ID действия. Не передавайте внутренние URL поставщика или его названия маршрутов.

## Запрос

| Поле     | Тип    | Обязательно | Описание                                                                          |
| -------- | ------ | ----------: | --------------------------------------------------------------------------------- |
| `action` | string |          Да | ID действия BeatAPI из каталога.                                                  |
| `params` | object |         Нет | Параметры из выбранной записи каталога. Если параметров нет, поле можно опустить. |

В `action` используйте формат идентификатора из каталога, например `douyin.web.fetch_one_video`. Поле `input_schema` записи определяет обязательные поля, типы и допустимые значения. Если метод действия в каталоге — `GET`, значения параметров должны быть скалярными. Для `POST` поле `params` — объект JSON.

Максимальный размер тела запроса — 512 KiB. Для авторизации используется `Authorization: Bearer <BeatAPI API key>`. При возможных повторах одного запроса можно передать `Idempotency-Key`. Тот же ключ с другим запросом будет отклонён.

## Ответ

Успешный вызов возвращает стандартный объект BeatAPI:

```json
{
  "object": "social_data.call",
  "status": "succeeded",
  "request_id": "req_01H...",
  "action": "douyin.web.fetch_one_video",
  "data": {
    "aweme_id": "7364837462110"
  }
}
```

Поле `data` содержит общедоступный результат выбранного действия. Перед возвратом BeatAPI удаляет названия поставщиков, их ID запросов, URL кэша, поля маршрутизации и внутренние ошибки поставщиков. Ответ синхронный: успешный HTTP-ответ означает завершение действия.

Статический каталог описывает входные данные, но не выход каждого действия. Через [Capabilities Inspect](/capabilities) проверьте актуальную `output_schema` и готовность. Статус `runnable` означает, что действие выполняется, но структура результата не опубликована. Читайте поля фактического ответа, не предполагая фиксированной схемы.

## Поиск авторов

Два действия решают задачи, которых нет в обычном каталоге платформ: найти похожих авторов
и их контактные данные. Они используют тот же метод API и тот же
контракт `action` / `params`, что и остальные действия.

### `creator.discover`

По одному исходному аккаунту возвращаются авторы, которых сама платформа считает похожими,
с опубликованными в их профилях контактными данными.

| Параметр   | Тип     | Обязателен | Описание                                                                                                                       |
| ---------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `platform` | string  | Да         | `instagram`. Используется граф похожих аккаунтов Instagram; для других платформ такого поиска от исходного аккаунта здесь нет. |
| `seed`     | string  | Да         | Имя аккаунта или URL профиля, например `gymshark` или `https://www.instagram.com/gymshark/`.                                   |
| `limit`    | integer | Нет        | Сколько похожих авторов вернуть: `1`–`6`, по умолчанию `6`.                                                                    |

```bash
curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"creator.discover","params":{"platform":"instagram","seed":"gymshark","limit":3}}'
```

Исходный аккаунт также возвращается вместе с найденными авторами с меткой
`discovered_via: "input"`. Поэтому `limit` ограничивает число похожих авторов,
а строк в ответе будет на одну больше.

### `creator.contacts`

Для уже известных авторов возвращается такая же запись по каждому, без
этапа поиска похожих аккаунтов.

| Параметр   | Тип       | Обязателен | Описание                             |
| ---------- | --------- | ---------- | ------------------------------------ |
| `platform` | string    | Да         | `instagram`, `tiktok` или `youtube`. |
| `handles`  | string\[] | Да         | 1–8 имён аккаунтов или URL профилей. |

```bash
curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"creator.contacts","params":{"platform":"youtube","handles":["@mkbhd"]}}'
```

### Запись автора

Оба действия возвращают одинаковую структуру в `data`: по объекту на автора.

| Поле                                                                                    | Описание                                                                                  |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `platform`, `handle`, `name`, `profile_url`, `user_id`                                  | Идентификационные данные.                                                                 |
| `followers`, `following`, `posts_count`, `engagement_rate_pct`, `avg_likes`             | Аудитория и активность. `followers_estimated` указывает, что число оценено.               |
| `email`, `extra_emails`, `email_status`, `email_source`                                 | Контакты. Если адрес не опубликован, `email` равен `null`; см. ниже.                      |
| `website`, `linkedin_url`, `instagram_url`, `tiktok_url`, `youtube_url`, `facebook_url` | Ссылки из профиля.                                                                        |
| `bio`, `category`, `country`, `verified`, `is_business`, `is_private`                   | Свойства профиля.                                                                         |
| `lead_score`, `lead_grade`, `lead_tier`                                                 | Оценка по перечисленным полям для первичного отбора.                                      |
| `discovered_via`                                                                        | `input` для указанного вами автора, `instagram_related` для найденного похожего аккаунта. |

> **Warning**
>
> Поле `email_source` показывает, откуда получен адрес. На сайте, на который ссылается
> автор, адрес может принадлежать рекламируемому бренду, а не самому автору.
> Проверьте `email_source`, прежде чем считать адрес личным контактом.

### Оплата

В отличие от остальных действий, эти два оплачиваются **за возвращённого автора**, а не
за запрос. Это указано в поле `billing_unit` метода `GET /v1/social-data/pricing`:
`"creator"` для этих двух действий, `"request"` для остальных.

Если никто не найден, запрос считается успешным и возвращает пустой массив `data`.
При этом списывается стоимость одного автора: поиск выполнен независимо от результата.
Ограничивайте расходы значением `limit` и
числом элементов `handles`.

## Ошибки и оплата

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

| HTTP-статус | Код                                                    | Значение                                                              |
| ----------: | ------------------------------------------------------ | --------------------------------------------------------------------- |
|         400 | `bad_request`                                          | Некорректный JSON, действие или параметры; в сообщении названо поле.  |
|         401 | `missing_api_key` / `invalid_api_key`                  | Ключ не передан, неверен, просрочен, отключён или его лимит исчерпан. |
|         402 | `insufficient_credits`                                 | Баланс равен нулю или меньше стоимости вызова.                        |
|         403 | `forbidden`                                            | Ключу или аккаунту запрещён этот вызов.                               |
|         404 | `not_found`                                            | Запрошенное действие или ресурс не найден.                            |
|         409 | `idempotency_conflict`                                 | Ключ идемпотентности повторно использован для другого запроса.        |
|         429 | `rate_limit_exceeded`                                  | Достигнут лимит запросов. Подождите `Retry-After` секунд.             |
|         500 | `internal_error`                                       | Непредвиденная внутренняя ошибка. Повтор допустим.                    |
|         503 | `processing_unavailable` или другой код `processing_*` | Запрос не завершён. Повторите позже с увеличением задержки.           |

Неудачные вызовы не расходуют средства. Успешный вызов оплачивается по текущим тарифам BeatAPI аккаунта и выбранному действию. Затраты поставщиков и их URL не входят в документацию или публичный ответ.

## MCP

Те же каталог и контракт доступны через MCP-инструменты `capabilities_search`, `capabilities_inspect`, `capabilities_run` и [Capabilities API](/capabilities). Ищите по платформе и действию словами пользователя (`小红书 搜索笔记`, `tiktok user profile`). Одно название платформы возвращает обзор с группировкой по функциям. Передавайте `data:<action-id>` точно из Search и следуйте полю `next` каждого ответа.

Для больших результатов MCP по умолчанию возвращает сокращённый просмотр. Полный результат можно бесплатно получить в течение часа: используйте тот же ключ и исходный `reference`, задайте `operation` равным `"result"` и передайте возвращённый `request_id`. Учётные данные поставщиков и их внутренние пути не нужны.