# Данные X

Получайте профили X, ищите пользователей и посты, а также постранично обрабатывайте ленты и ответы.

Выберите операцию для нужных вам данных. Все пять конечных точек используют POST и возвращают JSON в корне, без общего обертки `data`.

Во всех примерах используется `FELO_API_KEY` из [обзора](https://openapi.felo.ai/ru/docs/data-api/guides/felo-overview.md). Вызовы используют **баланс платформы**, а не кредиты Felo Pro. Примеры ответов носят иллюстративный характер; фактический контент и необязательные поля могут отличаться.

## Выберите операцию

| Нужда | Конечная точка |
|---|---|
| Профили для известных имен пользователей | `POST /api/v1/data/x/user/info` |
| Найти пользователей по поисковому запросу | `POST /api/v1/data/x/user/search` |
| Посты одного пользователя | `POST /api/v1/data/x/user/tweets` |
| Посты, соответствующие запросу | `POST /api/v1/data/x/tweet/search` |
| Ответы на известные посты | `POST /api/v1/data/x/tweet/replies` |

## 1. Получить профили пользователей

`POST /api/v1/data/x/user/info`

| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
| `usernames` | string array | Да | 1–100 имен пользователей; отправляйте хэндлы без `@` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'
```

Ответ содержит `users` и `total`. Каждый пользователь включает `user_id`, `username` и `display_name`; также могут присутствовать текст профиля, число подписчиков, верификация и другие метаданные. Пакет может вернуть меньше профилей, чем запрошено. Сопоставляйте по имени пользователя или ID, а не по позиции в массиве.

```json
{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}
```

## 2. Поиск пользователей

`POST /api/v1/data/x/user/search`

| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
| `query` | string | Да | 1–1,000 символов |
| `cursor` | string | Нет | Курсор пагинации, до 4,000 символов |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'
```

Ответ содержит `users`, `total`, `has_next` и `next_cursor`. У этой операции нет параметра `limit`.

```json
{"users":[],"total":0,"has_next":false,"next_cursor":null}
```

## 3. Получить ленту пользователя

`POST /api/v1/data/x/user/tweets`

| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
| `username` | string | Требуется один идентификатор | Хэндл пользователя, до 100 символов |
| `x_user_id` | string | Требуется один идентификатор | ID пользователя, до 100 символов; имеет приоритет над `username` |
| `limit` | integer | Нет | 1–1,000; текущая реализация использует не менее 20, значение по умолчанию 20 |
| `cursor` | string | Нет | Курсор пагинации, до 4,000 символов |
| `include_replies` | boolean | Нет | Включать вложенные ответы; по умолчанию `false` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'
```

Ответ содержит `tweets`, `total`, `has_next` и `next_cursor`. Установка `limit` ниже 20 не гарантирует меньшее число возвращенных элементов или меньший счет. Включение ответов может добавить возвращаемые данные и результаты, подлежащие тарификации.

### Ограничения результатов и вложенных ответов

`limit` — это целевое число для верхнеуровневых постов в этом запросе, а не гарантированное количество результатов. Текущая реализация использует цель не менее 20: цель 20 читает одну вышестоящую страницу; большие цели автоматически выбирают до 50 страниц. Перед каждой страницей проверяется прошедшее время, и дальнейшее чтение останавливается, когда оно превышает 60 секунд. Эта проверка не гарантирует, что весь HTTP-запрос завершится в течение 60 секунд.

Сбор также останавливается, когда цель достигнута, у вышестоящего источника нет следующей страницы, страница пуста или курсор отсутствует. Успешный ответ, таким образом, может содержать меньше постов, чем `limit`. Используйте `has_next` и `next_cursor`, чтобы продолжить, если они доступны.

При `include_replies=true` каждый возвращенный пост получает до 5 дополнительных страниц и не более 100 вложенных ответов. Сбор может остановиться раньше, если нет следующей страницы, страница пуста или курсор не может продвинуться. Эти вложенные ответы находятся вне верхнеуровневого `limit` и `total`, но могут добавлять результаты, подлежащие тарификации.

Вложенные `replies` не являются полным архивом ответов и не предоставляют отдельный курсор продолжения для этого дополнительного сбора. Чтобы постранично получать ответы независимо, используйте операцию чтения ответов и возвращаемый ею курсор. Не переиспользуйте курсор верхнеуровневого поста для ответов.

## 4. Поиск постов

`POST /api/v1/data/x/tweet/search`

| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
| `query` | string | Да | Текст поиска, 1–1,000 символов |
| `query_type` | string | Нет | `Latest` (по умолчанию) или `Top` |
| `limit` | integer | Нет | 1–1,000; текущая реализация использует не менее 20, значение по умолчанию 20 |
| `cursor` | string | Нет | Курсор пагинации, до 4,000 символов |
| `since_time` | integer or string | Нет | Время начала; используйте Unix-секунды для однозначного числового значения |
| `until_time` | integer or string | Нет | Время окончания; используйте Unix-секунды, а не миллисекунды |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'
```

Ответ содержит `tweets`, `total`, `has_next` и `next_cursor`. Объекты постов включают `id`, `content`, `author`, `created_at` и `metrics`; ответы и цитируемые/репостнутые посты могут быть вложенными. Считайте ID строками.

### Ограничения количества результатов

`limit` — это цель, а не гарантия. Текущая реализация использует цель не менее 20: цель 20 читает одну вышестоящую страницу; большие цели автоматически выбирают до 50 страниц. Перед каждой страницей проверяется прошедшее время, и дальнейшие страницы не выбираются, когда оно превышает 60 секунд. Уже выполняющийся запрос к вышестоящему источнику все еще может занять время, поэтому это не является общим HTTP-тайм-аутом.

Сбор также останавливается, когда цель достигнута, у вышестоящего источника нет следующей страницы, страница пуста или курсор отсутствует. Возврат меньшего числа постов, чем `limit`, не означает, что запрос не удался или что каждый совпадающий пост был получен. Перед продолжением проверьте `has_next` и `next_cursor`.

```json
{
  "tweets": [{
    "id":"example-post-id",
    "content":"Example post content",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}
```

## 5. Читать ответы

`POST /api/v1/data/x/tweet/replies`

| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
| `tweet_ids` | string or string array | Да | Один ID поста или пакет до 20 ID |
| `cursor` | string | Нет | До 4,000 символов; используйте с одним ID поста |
| `since_time` | integer | Нет | Время начала в Unix-секундах |
| `until_time` | integer | Нет | Время окончания в Unix-секундах |

Замените заполнитель на реальный ID поста:

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'
```

В отличие от ленты и поиска постов, ответы сгруппированы под `results`. У каждой записи есть собственное состояние пагинации:

```json
{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}
```

### Ограничения ответов на один запрос

Каждый запрос читает одну вышестоящую страницу ответов для каждого `tweet_id` и сохраняет не более 100 ответов; он не выбирает автоматически все страницы ответов. В пакете до 20 ID ограничение в 100 ответов применяется отдельно к каждой записи `results`. Фактическое количество может быть меньше.

Поле `total` каждой записи — это число ответов, возвращенных в этой записи, а не полный счет ответов на пост. Чтобы продолжить, используйте `next_cursor` этой записи и отправляйте в следующем запросе только один ID поста. Параметра `limit` для увеличения верхнего предела на один запрос нет.

## Пагинация и контроль затрат

`total` считает соответствующий массив в текущем ответе: посты верхнего уровня для запросов постов или ответы внутри каждой записи результата для запросов ответов. Это не глобальное число совпадений, не полный счет ответов на пост и не итоговое число для биллинга.

1. Отправьте первый запрос без `cursor`.
2. Прочитайте `has_next` и `next_cursor` из ответа. Для ответов читайте их в каждой записи результата.
3. Если существует следующая страница и курсор непуст, отправьте его без изменений с тем же запросом. Для пакета ответов продолжайте по каждому посту отдельно.
4. Остановитесь, когда следующей страницы нет, курсор повторяется или достигнут ваш собственный предел страниц либо расходов.

Метаданные пагинации отражают последний ответ вышестоящего источника; возвращенная коллекция может быть усечена из-за ограничения по результатам. Даже `has_next=false` не гарантирует, что вся история X или все ответы были получены. Отображайте фактически возвращенное количество вместо того, чтобы помечать ограниченный набор результатов как все доступные данные.

За каждую успешную страницу может взиматься плата. Эти пять операций тарифицируются по возвращенным результатам, а не по фиксированной плате за запрос. Вложенные ответы и другие возвращенные записи могут влиять на число подлежащих оплате результатов; не оценивайте стоимость только по длине верхнеуровневого массива. Проверьте [текущие цены](https://openapi.felo.ai/api/v1/data/prices) и использование в консоли. Полные поля объектов находятся в [схеме OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).