XTwitterスクレイピングAPIチュートリアル

APIでX(Twitter)のポストを検索・収集する方法

非同期エンドポイントと正規化されたJSONで、Xの公開プロフィール、ポスト、タイムライン、検索、返信、引用を収集する方法を解説します。

SocQ2026年9月10日更新約11分で読めます

Xはブラウザ上では今もタイムラインのように見えます。しかし、公開データの仕様はもっと厳密です。ユーザー名はポストのURLではなく、引用はリポストではなく、返信は引用ではありません。削除されたポストや非公開のポストは、空のレコードになるのではなく、きちんと失敗する必要があります。

このチュートリアルでは、SocQ X APIを使って本番向けのワークフローを構築します。公式APIと公開データAPIの違い、エンドポイントの使い分け、入力値の整え方、非同期タスク、フィールドの意味、更新頻度、責任ある利用までを扱います。

結論: ユーザー名、x.comまたはtwitter.comのステータスURL、あるいは検索クエリをPOST /v1/x/{resource}に送信し、タスクIDを保存して、/v1/tasks/{id}をポーリングします。リソースを区別する列を持たせずに、引用、リポスト、返信を1つのテーブルにまとめないでください。

公式のX APIか、公開データAPIか

公式のX APIは有料で、権限の許可が必要です。ポストの投稿、ダイレクトメッセージの送信、広告の管理、ユーザーとしてのフォローやいいね、ストリームやその他のアカウント認可が必要な機能を使いたい場合は、公式のX APIが正しい製品です。アクセス条件や料金は変わるため、書き込み系やパートナー向けの製品については、現在の開発者向けドキュメントを正としてください。

SocQは、対応しているプロフィール、既知のポスト、ユーザーのポスト期間、検索、会話のエッジ、トレンドを対象とした、公開データの読み取りレイヤーです。Xのユーザーとして認証することはなく、公式の投稿機能や広告機能の代わりにはなりません。料金とベンダーの位置づけについては、Twitter API代替サービス、Twitter スクレイパーAPI比較、TwitterAPI.ioの代替サービスをご覧ください。エンドポイントを選ぶ前に、アクセスモデルを選んでください。

適切なXエンドポイントを選ぶ

リソースエンドポイント受け付ける公開入力主な用途
プロフィール/v1/x/profilesユーザー名(@の有無は問わない)公開されているアイデンティティと表示されている数値
ポスト/v1/x/postsx.comまたはtwitter.comのステータスURL既知のポスト1件
ユーザーのポスト/v1/x/user-postsユーザー名アカウントの最近の公開ポスト
検索/v1/x/searchクエリ最新またはトップの公開ポストの探索
返信/v1/x/post-repliesステータスURL既知のポストへの返信
引用/v1/x/post-quotesステータスURL既知のポストの引用ポスト

次のエンドポイントも利用できます。

引用、リポスト、返信は、それぞれ別のリソースです。引用には、それ自体のポスト本文があります。リポストしたユーザーの一覧は、プロフィールの集合です。返信は、会話に属するポストです。これらを同じオブジェクトであるかのようにアップサートしないでください。

ユーザー名、URL、クエリを正規化する

送信された値は保持したうえで、コピーを整形します。

  1. @の有無にかかわらずユーザー名を受け付け、保存するときは正規の形式のユーザー名1つに統一する。
  2. x.comとtwitter.comの両方のホストを受け付ける。ポストを対象とするエンドポイントでは、数値の/status/{id}パスを必須にする。
  3. トラッキング用のクエリパラメータを取り除く。ステータスIDが保たれていれば、特定のモバイルやロケールのホストは要求しない。
  4. ユーザー名は大文字小文字を区別せずに、ポストはステータスIDで重複を排除する。
  5. 空のクエリとユーザー名は、送信前に弾く。
  6. 検索式は出自の行に保持し、アナリストが各ポストがデータセットに入った理由を説明できるようにする。

user-postsとsearchは、results_limitを20〜2000の範囲で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を読み取り、has_moreがtrueの間はnext_cursorを使って続きを取得します。

堅牢なワーカーは、次の情報を保存してください。

  • バッチIDとSocQのタスクID。
  • リソースと、正規化したユーザー名、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は出自として保持してください。

返信と引用は、ポストと同じ形を再利用します。リポストしたユーザーは、プロフィールと同じ形を再利用します。トレンドは、ロケール単位の探索用の行であり、ポストではありません。

削除されたポストや非公開のポストは、入力またはタスクの境界で失敗する必要があります。空のポストを挿入したり、エンゲージメントを0と偽ったり、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レスポンスに対する回数制限付きのリトライ、冪等なアップサートを追加してください。

ポストとメトリクスのスナップショットを分けてモデル化する

ポストの識別情報と、ポストのメトリクスは、変化する速さが異なります。

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

アップサートはresource + idで行います。引用、返信、元のポストを同じポストテーブルに保存してよいのは、resourceが必須の列として残る場合だけです。リポストしたユーザーは、プロフィールまたはエッジのテーブルに保存してください。

リポストしたユーザーのスナップショットから、引用の増加を計算しないでください。これらのメトリクスは互換ではありません。

保存前に検証する

  • platformはxと等しいこと。
  • resourceはエンドポイントと一致すること。
  • リソースがポスト形式の場合、ステータスURLに数値の/status/のIDが含まれること。
  • リソースがuser-postsでフィールドが存在する場合、投稿者のユーザー名は送信したアカウントと一致すること。
  • カウントは、負でない数値かnullであること。
  • タイムスタンプはパースできること。
  • 非公開または削除済みの入力が失敗した場合、成功した空のポストにしてはならない。

無効な行は、生のタスクのペイロードとともに隔離して保管してください。

エンティティごとに更新スケジュールを選ぶ

エンティティ開始時の妥当な頻度理由
プロフィール週次または月次プロフィール文やアイデンティティのフィールドは変化がゆるやか
既知のポストアクティブな間は1時間〜1日ごと公開メトリクスの変化が速い
ユーザーのポスト期間モニタリングでは1時間〜1日ごとタイムラインは範囲が限られ、ランク付けされている
検索クエリに合わせたスケジュールlatestとtopはアーカイブではない
返信・引用ポストがアクティブな間は1時間ごと会話のエッジはまとまって届く
フォロワー・フォロー中週次リストが大きく、200刻みで取得する
トレンド1時間ごと、または1日数回WOEIDのセットが入れ替わる

ビジネス上の問いに、より新しいスナップショットが不要なら、収集の頻度を減らしてください。

よくある失敗パターン

ポストのURLで何も返らない

URLが公開されていて、まだ利用可能で、/status/{id}を含んでいることを確認してください。削除されたポストや保護されたポストは、きちんと失敗するはずです。入力レベルのエラーは保持してください。

検索結果が不完全に見える

results_limitはリクエストの上限です。ランキング、インデックス、latestとtopの切り替えのいずれもが、取得されるページを変えます。クエリとソートは、レコードとあわせて保存してください。

引用がリポストとして保存された

これらは別のエンドポイントで、別のオブジェクトです。resourceを主キーに含めてください。

フォロワーのジョブが上限値を拒否する

フォロワーとフォロー中は、200〜2000の範囲で200刻みの値を受け付けます。ユーザーのポストと検索は、20刻みです。

メトリクスがブラウザの表示と一致しない

公開されているカウントはスナップショットです。遅延したり、丸められたり、非表示になったりすることがあります。パーサーを疑う前に、collected_atを比較してください。

同じユーザーが2回出てくる

ユーザー名を正規化し、安定した公開IDを優先してください。アカウント名が変更された場合に備えて、エイリアスのテーブルを保持します。

Xのデータを責任をもって利用する

正当な目的に必要な公開フィールドだけを収集してください。保護されたアカウント、ブロック、ログインの壁、その他のアクセス制御を回避しないでください。センシティブな個人のプロファイリングや、人に重大な影響を与えうる自動化された判断は、安全策なしには行わないでください。

Xのデータは個人データにあたる場合があります。必要に応じて適法な根拠を確立し、保持と削除のルールを定め、APIキーとエクスポートを保護し、Xの現行の利用規約を資格のある専門家とともに確認してください。公開データAPIは、ポストやメディアを再公開するライセンスを与えるものではありません。

よくある質問(FAQ)

XやTwitterのスクレイピングは合法ですか?

一律の答えはありません。管轄、データ、手法、目的、契約、安全策によって異なります。このチュートリアルは法的助言ではありません。

これは公式のX APIの代わりになりますか?

いいえ。投稿、DM、広告、ストリーム、その他の許可が必要な操作には、引き続き公式のアクセスが必要です。SocQは、対応している公開データの読み取りをカバーします。

非公開または削除済みのポストを収集できますか?

いいえ。そうした入力は、きちんと失敗するはずです。保護を回避しないでください。

引用はリポストと同じですか?

いいえ。引用はポストです。リポストしたユーザーはプロフィールです。返信は3つ目のリソースです。

検索は完全な履歴を返しますか?

いいえ。1つのクエリに対して、限られた範囲を並べた結果を返します。

重複排除にはどのキーを使うべきですか?

resource + idを優先してください。公開IDがない場合は、正規化したステータスURLまたはユーザー名にフォールバックします。

X API

公開XのURLでワークフローを試す

公開データの入力を送信すると、取得元をたどれるコンテキスト付きの正規化レコードを受け取れます。

XのAPIを見る