XTwitterпарсингруководство по API

Как искать и собирать посты X/Twitter через API

Сбор публичных профилей, постов, лент, результатов поиска, ответов и цитат X через асинхронные эндпоинты с нормализованным JSON.

SocQОбновлено 10 сентября 2026 г.8 мин чтения

В браузере X по-прежнему выглядит как лента. Спецификация публичных данных уже: имя пользователя — это не URL поста, цитата — это не репост, ответ — это не цитата, а удаленный или защищенный пост должен корректно завершаться ошибкой, а не превращаться в пустую запись.

В этом руководстве строится продакшен-процесс на основе API SocQ для X. Рассматриваются официальный и публичный доступ, маршрутизация по эндпоинтам, подготовка входных данных, асинхронные задачи, смысл полей, частота обновления и ответственное использование.

Коротко: отправляйте имена пользователей, URL постов x.com или twitter.com или поисковый запрос на POST /v1/x/{resource}, сохраняйте ID задачи и опрашивайте /v1/tasks/{id}. Не сводите цитаты, репосты и ответы в одну таблицу без поля, различающего ресурсы.

Официальный API X или API публичных данных?

Официальный API X платный и требует разрешений. Это правильный продукт, когда нужно публиковать, отправлять личные сообщения, управлять рекламой, подписываться или ставить лайки от имени пользователя либо получать потоки и другие данные, доступные при авторизации аккаунта. Условия доступа и цены меняются; для продуктов записи и партнерских продуктов источником истины считайте текущую документацию для разработчиков.

SocQ — уровень чтения публичных данных для поддерживаемых профилей, известных постов, окон постов пользователя, поиска, связей в обсуждениях и трендов. Он не аутентифицируется как пользователь X и не заменяет официальные инструменты публикации и рекламы. О ценах и сравнении поставщиков читайте в статьях альтернативы API Twitter, API для парсинга Twitter и альтернативы TwitterAPI.io. Выберите модель доступа до выбора эндпоинта.

Выбор правильного эндпоинта X

РесурсЭндпоинтПринимаемый публичный входТипичное применение
Профили/v1/x/profilesИмена пользователей, с @ или безПубличная идентичность и видимые счетчики
Посты/v1/x/postsURL постов x.com или twitter.comОдин известный пост
Посты пользователя/v1/x/user-postsИмена пользователейНедавние публичные посты аккаунта
Поиск/v1/x/searchЗапросПоиск публичных постов в режиме Latest или Top
Ответы/v1/x/post-repliesURL постовОтветы на известный пост
Цитаты/v1/x/post-quotesURL постовЦитаты известного поста

Также доступны:

Цитаты, репосты и ответы — разные ресурсы. У цитаты есть собственный текст поста. Список сделавших репост — это набор профилей. Ответ — это пост, принадлежащий обсуждению. Не выполняйте для них upsert так, будто это один и тот же объект.

Нормализация имен пользователей, URL и запросов

Сохраняйте отправленное значение, затем очищайте его копию:

  1. Принимайте имена пользователей с @ или без, затем сохраняйте одно каноническое имя.
  2. Принимайте оба домена — x.com и twitter.com. Для эндпоинтов, работающих с постами, требуйте числовой путь /status/{id}.
  3. Удаляйте параметры запроса для отслеживания. Не требуйте конкретного мобильного домена или домена с локалью, если ID поста не поврежден.
  4. Удаляйте дубликаты имен пользователей без учета регистра, а постов — по ID поста.
  5. Отклоняйте пустые запросы и имена пользователей до отправки.
  6. Храните поисковые выражения в строке сведений о происхождении, чтобы аналитики могли объяснить, почему пост попал в датасет.

user-posts и search принимают results_limit от 20 до 2 000 с шагом 20. Для поиска sort_by принимает значения latest или top. post-replies также принимает sort_by со значением relevance, latest или likes.

Отправка задачи сбора

Сбор профилей:

curl -X POST "https://api.socq.ai/v1/x/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["openai","@github"]}'

Сбор известных постов с любого из доменов:

curl -X POST "https://api.socq.ai/v1/x/posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"]}'

Сбор окна постов пользователя:

curl -X POST "https://api.socq.ai/v1/x/user-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["openai","github"],"results_limit":40}'

Поиск публичных постов:

curl -X POST "https://api.socq.ai/v1/x/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI lang:en","results_limit":100,"sort_by":"latest"}'

Собирайте ответы и цитаты отдельными заданиями:

curl -X POST "https://api.socq.ai/v1/x/post-replies" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20,"sort_by":"latest"}'
curl -X POST "https://api.socq.ai/v1/x/post-quotes" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20}'

Сохраняйте возвращенный ID задачи вместе с названием ресурса и каноническими входными данными.

Опрос задачи без создания дубликатов

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Статусы queued и running — это нормальное состояние. Используйте экспоненциальную задержку. Когда задача завершится успешно, читайте data.results.items и переходите по next_cursor, пока has_more равно true.

Надежный воркер должен сохранять:

  • ID пакета и ID задачи SocQ.
  • Ресурс и канонические имена пользователей, URL или запрос.
  • Время отправки и завершения.
  • Конечный статус и категорию ошибки.
  • Последний обработанный курсор результатов.

Перезапуск воркера — не причина повторно отправлять тот же поиск.

Возвращаемые поля

У записей есть общие поля id, platform, resource, type, url, created_at, collected_at и extra.

Профиль включает username, name, description, avatar_url, cover_url, is_verified, is_private и видимые метрики. Защищенные аккаунты не являются целью сбора публичных данных.

Пост включает text, language, author, видимые метрики, media, hashtags и mentions, если они публичны. Используйте id как предпочтительный ключ сущности, а URL поста — как сведения о происхождении.

Ответы и цитаты используют структуру поста. Список сделавших репост использует структуру профиля. Тренды — это строки результатов, привязанные к местоположению, а не посты.

Удаленные и закрытые посты должны завершаться ошибкой на уровне входных данных или задачи. Не вставляйте пустой пост, не придумывайте нулевую вовлеченность и не используйте collected_at вместо created_at.

Результаты поиска — это ранжированная выдача. latest и top — это разные способы упорядочивания ограниченного окна, а не полный исторический архив.

Python-воркер для профилей, постов и поиска

import time
import requests

BASE = "https://api.socq.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {SOCQ_API_KEY}",
    "Content-Type": "application/json",
}

def collect(resource, payload):
    created = requests.post(
        f"{BASE}/x/{resource}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    created.raise_for_status()
    task_id = created.json()["data"]["task_id"]

    delay = 2
    while True:
        response = requests.get(
            f"{BASE}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()["data"]

        if task["status"] == "succeeded":
            return task["results"]["items"]
        if task["status"] in {"failed", "cancelled"}:
            raise RuntimeError(task)

        time.sleep(delay)
        delay = min(delay * 1.5, 15)

profiles = collect("profiles", {"usernames": ["openai"]})
hits = collect("search", {
    "query": "AI lang:en",
    "results_limit": 40,
    "sort_by": "latest",
})

Прежде чем выпускать это в продакшен, добавьте курсорную пагинацию, ограниченное число повторных попыток для тайм-аутов и 5xx-ответов, допускающих повтор, а также идемпотентный upsert.

Разделяйте посты и снимки метрик

Идентичность поста и его метрики меняются с разной скоростью.

x_entity
  resource
  platform_id
  canonical_url_or_username
  text_or_description
  author_id
  created_at
  first_seen_at
  last_seen_at

x_snapshot
  resource
  platform_id
  collected_at
  likes_count
  replies_count
  reposts_count
  quotes_count
  source_task_id

Выполняйте upsert по resource + id. Храните цитаты, ответы и исходные посты в одной таблице постов, только если resource остается обязательным столбцом. Список сделавших репост храните в таблице профилей или связей.

Не вычисляйте рост числа цитат по снимку списка сделавших репост. Эти метрики не взаимозаменяемы.

Проверка перед сохранением

  • platform должно быть равно x.
  • resource должно соответствовать эндпоинту.
  • URL постов должны содержать числовой ID в /status/, если ресурс работает с постами.
  • Имена авторов должны совпадать с отправленным аккаунтом, если ресурс — user-posts и поле присутствует.
  • Счетчики должны быть неотрицательными числами или null.
  • Временные метки должны корректно разбираться.
  • Неудавшийся закрытый или удаленный вход не должен превращаться в успешный пустой пост.

Храните невалидные строки в карантине вместе с исходными данными задачи.

Расписание обновления по типу сущности

СущностьРазумная начальная частотаПричина
ПрофильРаз в неделю или в месяцОписание профиля и поля идентичности меняются медленно
Известный постОт раза в час до раза в день, пока активенПубличные метрики быстро меняются
Окно постов пользователяОт раза в час до раза в день для мониторингаЛенты ограничены и ранжированы
ПоискПо расписанию, соответствующему запросуlatest и top — это не архивы
Ответы / цитатыРаз в час, пока пост активенСвязи в обсуждении появляются всплесками
Подписчики / подпискиРаз в неделюСписки большие, шаг — 200
ТрендыРаз в час или несколько раз в деньНаборы по WOEID меняются

Сокращайте сбор, если для бизнес-вопроса не нужен более свежий снимок.

Типичные сбои

URL поста ничего не возвращает

Убедитесь, что URL публичный, по-прежнему доступен и содержит /status/{id}. Удаленные и защищенные посты должны корректно завершаться ошибкой. Сохраняйте ошибку на уровне входных данных.

Поиск выглядит неполным

results_limit ограничивает запрос. Ранжирование, индексация и выбор между latest и top меняют страницу. Храните запрос и сортировку вместе с записями.

Цитаты сохранились как репосты

Это разные эндпоинты и разные объекты. Включайте resource в первичный ключ.

Задания по подписчикам отклоняют лимит

Эндпоинты подписчиков и подписок принимают значения от 200 до 2 000 с шагом 200. User-posts и search используют шаг 20.

Метрики расходятся с браузером

Публичные счетчики — это снимки. Они могут запаздывать, округляться или скрываться. Сравните collected_at, прежде чем винить парсер.

Один и тот же пользователь встречается дважды

Приводите имена пользователей к каноническому виду и отдавайте предпочтение стабильному публичному ID. Ведите таблицу псевдонимов на случай переименования аккаунта.

Ответственное использование данных X

Собирайте только публичные поля, необходимые для законной цели. Не обходите защищенные аккаунты, блокировки, требования входа и другие механизмы контроля доступа. Избегайте профилирования отдельных людей по чувствительным признакам и автоматизированных решений, которые могут существенно повлиять на человека, без мер защиты.

Данные X могут быть персональными данными. Определите правовое основание, где это требуется, задайте правила хранения и удаления, защищайте API-ключи и выгрузки и изучите текущие условия X с квалифицированным юристом. API публичных данных не дает лицензии на повторную публикацию постов или медиа.

Часто задаваемые вопросы

Законен ли парсинг X или Twitter?

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

Заменяет ли это официальный API X?

Нет. Официальный доступ по-прежнему необходим для публикации, личных сообщений, рекламы, потоков и других действий, требующих разрешений. SocQ покрывает поддерживаемое чтение публичных данных.

Можно ли собирать закрытые или удаленные посты?

Нет. Такие входные данные должны корректно завершаться ошибкой. Не обходите защиту.

Цитаты — это то же самое, что репосты?

Нет. Цитаты — это посты. Список сделавших репост — это профили. Ответы — третий ресурс.

Возвращает ли поиск полную историю?

Нет. Он возвращает ограниченное упорядоченное окно для одного запроса.

Какой ключ использовать для удаления дубликатов?

Предпочтительно resource + id. Если публичный ID отсутствует, используйте нормализованный URL поста или имя пользователя.

X API

Проверить сценарий на публичном URL X

Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.

API для X