Справочник API: все эндпоинты и параметры

Базовый URL

https://xcrap.cc/v1

Без авторизации

Нет ни ключа, ни токена, ни заголовка, который надо отправлять. Лимиты считаются по IP и по эндпоинту.

OpenAPI

Полная спецификация отдаётся в JSON и YAML. Направьте на неё любой генератор или агентный фреймворк.

Форматы ответа

По умолчанию JSON. Переопределяется через ?format= или заголовок Accept. Работают они одинаково; если заданы оба, побеждает query-параметр.

?format=	Accept	Content-Type
`json`	`application/json`	`application/json`
`markdown`	`text/markdown`	`text/markdown`
`yaml`	`application/yaml`	`application/yaml`
`csv`	`text/csv`	`text/csv`
`html`	`text/html`	`text/html`

x-markdown-tokens

Каждый markdown-ответ содержит оценку стоимости чтения, чтобы агент мог решить, поместится ли тред в контекст, до загрузки тела.

Лимиты запросов

Лимиты заданы на эндпоинт, а не одним общим бюджетом: bulk-запрос может стоить пятидесяти обращений наверх, а закэшированный пост — ни одного. В каждом ответе есть x-ratelimit-limit, x-ratelimit-remaining и x-ratelimit-reset.

Лимит	Запросы	Окно	Применяется к
`tweet`	45	1 мин	/v1/tweet
`user`	45	1 мин	/v1/user
`thread`	15	1 мин	/v1/thread
`timeline`	15	1 мин	/v1/user/tweets
`graph`	15	1 мин	/v1/user/followers, /v1/user/following
`replies`	15	1 мин	/v1/replies
`history`	4	5 мин	/v1/user/history
`search`	10	15 мин	/v1/search
`bulk`	6	5 мин	/v1/bulk
`media`	20	1 мин	/v1/media, /v1/media/download
`meta`	90	1 мин	/v1/trends
`page`	240	1 мин	Страницы сайта

Нужно больше? Тариф для компаний даёт повышенные лимиты и выделенные мощности. Тариф для компаний →

Ошибки

Ошибки приходят в запрошенном формате: стабильный машиночитаемый код, сообщение о том, что пошло не так, и подсказка, что с этим делать.

Статус	code	Что делать
400	`bad_request`	Параметр отсутствует или указан неверно. Сверьтесь с этой страницей.
404	`not_found`	Пост или аккаунт удалён, заблокирован, закрыт или никогда не существовал.
429	`rate_limited`	Бюджет эндпоинта исчерпан. Подождите время из retry-after или посмотрите тариф для компаний с повышенными лимитами.
451	`opted_out`	Этот аккаунт попросил исключить его из XCrap.
500	`internal_error`	Наша ошибка. Уже сообщено. Попробуйте чуть позже.
502	`upstream_failed`	Все источники отказали. Обычно ненадолго — повторите через минуту.
504	`upstream_timeout`	Источник не ответил вовремя. Повторите через минуту.
503	`search_unavailable`	Ресурс поиска пока исчерпан, или поиск не настроен. Подождите время из retry-after.

Попробовать

Заполните параметры и отправьте. Запрос уходит в настоящий API — ключ добавлять не нужно, так что между этой формой и живым ответом ничего нет.

GET /v1/tweet 45 / 1m

Один пост целиком

Возвращает один пост с автором, всеми счётчиками вовлечённости, вложенными медиа во всех битрейтах, результатами опросов и цитируемым постом, раскрытым на один уровень.

Параметры

Параметр	Тип	По умолчанию	Описание
`url` Обязательный	`string`	нет	URL поста или его числовой id. Подойдут x.com, twitter.com, зеркала fx/vx и просто id.
`download`	`boolean`	нет	Отправляет Content-Disposition, чтобы браузер сохранил ответ как файл.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/tweet?url=https://x.com/jack/status/20&format=markdown

Попробовать

url Обязательный

download

format

fresh

GET /v1/tweet

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/thread 15 / 1m

Весь тред по порядку

Передайте любой пост треда, включая первый, — и получите посты автора в порядке чтения. X показывает только родителя поста, поэтому XCrap сшивает ленту автора по id разговора, чтобы пройти тред вперёд.

Параметры

Параметр	Тип	По умолчанию	Описание
`url` Обязательный	`string`	нет	Любой пост треда.
`max_tweets`	`integer`	`25`	Глубина, от 1 до 100. Ответ сообщает, был ли тред обрезан.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/thread?url=https://x.com/naval/status/1002103360646823936&format=markdown

Попробовать

url Обязательный max_tweets

format

fresh

GET /v1/thread

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/replies 15 / 1m

Ответы под постом

Одна страница ответов на пост — сначала самые популярные или самые новые — вместе с самим постом. Возвращаются только прямые ответы: ответ на ответ относится к своему разговору. Пагинации нет: это единственная страница, которую X отдаёт для поста, — примерно до ста ответов.

Параметры

Параметр	Тип	По умолчанию	Описание
`url` Обязательный	`string`	нет	Пост, ответы на который нужно прочитать: URL или числовой id.
`sort`	`string`	`top`	top — сначала самые популярные, recent — сначала самые новые.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/replies?url=https://x.com/naval/status/1002103360646823936&sort=top&format=markdown

Попробовать

url Обязательный

sort

format

fresh

GET /v1/replies

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/search 10 / 15m

Поиск постов

Полнотекстовый поиск по X с операторами, которые понимает поиск X: from:, to:, "точная фраза", -исключение, lang:, filter:links и другие. Выберите самые новые или самые популярные посты либо только посты с фото или видео. Одна страница за вызов; для следующей передайте next_cursor. У поиска самый жёсткий лимит среди всех эндпоинтов, а результаты кэшируются на десять минут.

Параметры

Параметр	Тип	По умолчанию	Описание
`q` Обязательный	`string`	нет	Что искать, включая любые операторы поиска X.
`feed`	`string`	`latest`	latest, top, photos или videos.
`since`	`string`	нет	Самый старый подходящий пост: дата вроде 2025-01-01 или полная метка времени ISO.
`until`	`string`	нет	Самый новый подходящий пост: дата или полная метка времени ISO.
`cursor`	`string`	нет	next_cursor из предыдущего ответа.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/search?q=from:nasa%20mars&feed=latest&format=markdown

Попробовать

q Обязательный

feed

since until cursor

format

fresh

GET /v1/search

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/user 45 / 1m

Профиль

Био, местоположение, сайт, дата регистрации, тип верификации, аватар и баннер в полном разрешении, а также число подписчиков, подписок, постов и медиа.

Параметры

Параметр	Тип	По умолчанию	Описание
`handle` Обязательный	`string`	нет	Хэндл, с @ или без, или полный URL профиля.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/user?handle=naval&format=markdown

Попробовать

handle Обязательный

format

fresh

GET /v1/user

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/user/tweets 15 / 1m

Посты аккаунта

Страница постов аккаунта, от новых к старым. Пагинация по курсору, а не по смещению: лента меняется, пока вы её читаете, и смещение незаметно пропускало бы или повторяло посты.

Параметры

Параметр	Тип	По умолчанию	Описание
`handle` Обязательный	`string`	нет	Аккаунт для чтения.
`count`	`integer`	`20`	Сколько постов вернуть, от 1 до 100.
`cursor`	`string`	нет	next_cursor из предыдущего ответа.
`exclude_replies`	`boolean`	`true`	Не включать ответы аккаунта другим людям.
`media_only`	`boolean`	`false`	Только посты с изображением или видео.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/user/tweets?handle=naval&count=20

Попробовать

handle Обязательный count cursor

exclude_replies

media_only

format

fresh

GET /v1/user/tweets

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/user/followers 15 / 1m

Кто подписан на аккаунт

Страница аккаунтов, подписанных на этот, — каждый как полный профиль. Размер страницы решает X, обычно несколько десятков; для следующей страницы передайте next_cursor, на последней он равен null.

Параметры

Параметр	Тип	По умолчанию	Описание
`handle` Обязательный	`string`	нет	Аккаунт, подписчиков которого нужно показать.
`cursor`	`string`	нет	next_cursor из предыдущего ответа.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/user/followers?handle=jack&format=markdown

Попробовать

handle Обязательный cursor

format

fresh

GET /v1/user/followers

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/user/following 15 / 1m

На кого подписан аккаунт

Страница аккаунтов, на которые подписан этот, — каждый как полный профиль. Размер страницы решает X; для следующей страницы передайте next_cursor, на последней он равен null.

Параметры

Параметр	Тип	По умолчанию	Описание
`handle` Обязательный	`string`	нет	Аккаунт, подписки которого нужно показать.
`cursor`	`string`	нет	next_cursor из предыдущего ответа.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/user/following?handle=jack&format=markdown

Попробовать

handle Обязательный cursor

format

fresh

GET /v1/user/following

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/user/history 4 / 5m

Посты аккаунта оптом

Проходит ленту аккаунта и возвращает до 1 000 постов в одном ответе, от новых к старым, при желании — в пределах диапазона дат. Проход занимает примерно секунду на двадцать постов, поэтому для большого экспорта запросите format=ndjson: посты будут приходить по одному на строку по мере загрузки, примерно от новых к старым, а не все разом в конце. Чем дальше в прошлом диапазон, тем больше пробелов в ленте X, и диапазон многолетней давности может вернуться скудным или пустым.

Параметры

Параметр	Тип	По умолчанию	Описание
`handle` Обязательный	`string`	нет	Аккаунт для экспорта.
`max_posts`	`integer`	`200`	Остановиться после стольких постов, от 1 до 1000.
`since`	`string`	нет	Самый старый пост для включения: дата вроде 2025-01-01 или полная метка времени ISO.
`until`	`string`	нет	Самый новый пост для включения: дата или полная метка времени ISO.
`include_replies`	`boolean`	`false`	Включать ответы аккаунта другим людям.
`include_reposts`	`boolean`	`false`	Включить посты, которые аккаунт репостнул у других аккаунтов.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html, либо ndjson для потоковой выдачи по одному посту на строку. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/user/history?handle=naval&max_posts=200&since=2025-01-01

Попробовать

handle Обязательный max_posts since until

include_replies

include_reposts

format

fresh

GET /v1/user/history

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/trends 90 / 1m

Что в трендах

Текущие темы в трендах с меткой контекста, которую X добавляет к каждой. Кэшируются на пять минут, а не на пять дней: устаревший список трендов хуже, чем никакой.

Параметры

Параметр	Тип	По умолчанию	Описание
`count`	`integer`	`20`	Сколько тем, от 1 до 50.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/trends?count=10&format=markdown

Попробовать

count

format

fresh

GET /v1/trends

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/media 20 / 1m

Список медиа поста

Каждый файл, прикреплённый к посту: тип, размеры, длительность, альтернативный текст автора, все видеоварианты, закодированные X, и готовая ссылка на скачивание для каждого.

Параметры

Параметр	Тип	По умолчанию	Описание
`url` Обязательный	`string`	нет	Пост для проверки.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

https://xcrap.cc/v1/media?url=https://x.com/i/status/1671370010743263233

Попробовать

url Обязательный

format

fresh

GET /v1/media

Ограничения частоты действуют здесь ровно так же, как везде.

GET /v1/media/download 20 / 1m

Скачать один файл

Передаёт файл напрямую с заголовком Content-Disposition. Ничего не буферизуется и не пишется на наш диск — именно это на практике означает обещание о хранении из политики конфиденциальности.

Параметры

Параметр	Тип	По умолчанию	Описание
`url` Обязательный	`string`	нет	Пост, которому принадлежит файл.
`index`	`integer`	`0`	Какой файл, если в посте их несколько.
`quality`	`string`	`best`	best или worst. Только для видео; у изображений одно разрешение.

Пример

https://xcrap.cc/v1/media/download?url=https://x.com/i/status/1671370010743263233&index=0

Попробовать

url Обязательный index

quality

GET /v1/media/download

Ограничения частоты действуют здесь ровно так же, как везде.

POST /v1/bulk 6 / 5m

До пятидесяти постов за раз

Получает много постов одним запросом. Ошибки — поэлементные: битая ссылка вернёт ошибку для этой записи, а все остальные всё равно придут. GET тоже работает — с повторяющимися или разделёнными запятыми параметрами url.

Параметры

Параметр	Тип	По умолчанию	Описание
`urls` Обязательный	`string[]`	нет	От одного до пятидесяти URL или id постов в теле JSON.
`format`	`string`	`json`	Формат ответа: json, markdown, yaml, csv или html. Имеет приоритет над заголовком Accept.
`fresh`	`boolean`	`false`	Пропустить кэш и заново получить данные у источника. Используйте экономно.

Пример

curl -X POST https://xcrap.cc/v1/bulk \
  -H 'content-type: application/json' \
  -d '{"urls":["https://x.com/jack/status/20","1671370010743263233"]}'

Попробовать

body application/json

format

fresh

POST /v1/bulk

Ограничения частоты действуют здесь ровно так же, как везде.