X Thread Context
Xのスレッドは、同じ時間帯に投稿されたポストを単にまとめたものではなく、ポストとその返信先のメッセージ、返信チェーンをさかのぼった以前のメッセージ、そしてその後に続く返信をつなぐものです。これらの関係をポスト本文や投稿者情報とともに保持しておくと、ディスカッションがどう展開したかをたどり、個々のメッセージの文脈を理解しやすくなります。
X Thread Context API の主な機能
- 選んだポストを周辺のディスカッションとともに取得ポストのリンクを使い、対象メッセージに加えて、返信チェーンをさかのぼった以前の公開メッセージと、その後に続く取得可能な返信を取得します。選んだメッセージ単体を超えた文脈を把握できます。
- どのポストが同じ会話に属し、誰が誰に返信しているかを把握本文、投稿者、反応数に加え、conversation_id でポストが属する会話を、in_reply_to_id で直接の返信先ポストを特定できるため、個々のレコード間のつながりがわかります。
X Thread Context API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 必須。https://x.com/BaganiTohid/status/2110635249889919362 のように、/status/ の後に数値のポストIDが続く公開Xポストのリンクのリストです。Playgroundでは1行に1つずつリンクを入力するか、JSONの urls 配列を使用してください。プロフィールやコミュニティのリンクは使用できません。 |
results_limit | 任意 | 任意。入力ポストごとの文脈レコードの最大数で、1から2000まで指定でき、デフォルトは100です。ポストのリンクが2つで上限が20の場合、20件を共有するのではなく、それぞれ最大20件の関連レコードをリクエストします。 |
X Thread Context API の使い方
リクエストはバックグラウンドの取得タスクを開始するため、最初のレスポンスでは完成したデータではなくタスクIDが返されます。そのIDを使って進行状況を確認し、結果を取得します。
- 文脈を知りたい公開ポストのリンクをコピーし、そのポストについてリクエストする文脈レコードの件数を決めます。リンクが複数ある場合は、それぞれを urls リストに入れてください。
- 例を実行する前に、$SOCQ_API_KEY をご自身のAPIキーに置き換えるか、その環境変数を設定してください。下記の Authorization ヘッダーを付けてJSON入力を POST /v1/x/thread-context に送信し、レスポンスの task_id を保存します。
- 保存したIDで GET /v1/tasks/{task_id} を呼び出して進行状況を確認します。queued は待機中、running は取得中、retrying は再試行中を意味します。結果を読み取る前に succeeded になるまで待ってください。タスクが failed になった場合は、error_message で理由を確認してください。
- タスクが成功したら data.results.items を読み取ります。このリストの各項目が1件のポストと、取得可能な会話の関係を表します。リストが空の場合は、タスクがレコードを返さずに完了したことを意味します。
- data.results.has_more が true の場合、next_cursor の値は保存済み結果の次のページを示すマーカーです。その値をそのまま GET /v1/tasks/{task_id}?cursor=... の cursor パラメータにコピーし、has_more が false になるまで続けてください。
curl -X POST "https://api.socq.ai/v1/x/thread-context" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/BaganiTohid/status/2110635249889919362"],"results_limit":20}'X Thread Context API の主なユースケース
- 読むのに必要な文脈とともにメッセージを確認: 対象ポストを、返された以前のメッセージや返信(本文と投稿者を含む)と並べ、選んだメッセージが何に反応していたのかを確認する人のための閲覧ビューを用意します。
- 返された返信関係のマップ作成: conversation_id でポストをグループ化し、各 in_reply_to_id を他のレコードの id と照合して、存在する返信のつながりを描きます。参照先のポストが返されなかった箇所は欠落として見えるようにしておきます。
- 会話の要約に使う素材の準備: 完成した要約がレスポンスに含まれることを期待するのではなく、ポスト本文、投稿者名、日時、返信関係を順序付きの読み物セットとして保存し、人やソフトウェアによる別の要約工程に渡します。
X Thread Context API 活用のヒント
- 時系列に並べただけのリストでは各ポストがどのメッセージに答えているかがわからないため、ディスカッションを読みやすく並べる際は、まず関係IDでポストをつなぎ、投稿日時は補助的な情報としてのみ使用してください。
- in_reply_to_id が保存済みのレコードにないIDを参照している場合は、その返信を別のポストに付けたり欠けた本文を補ったりせず、欠落したリンクとして保持してください。
- 送信した複数のリンクが同じ会話に属する場合は、保存した結果をポストIDでマージし、共通の以前のポストが読み物セットに何度も現れないようにしてください。
- 選んだポストの返信だけが必要な場合は X Post Replies を、選んだポスト自体だけが必要な場合は X Posts を使用し、周辺の文脈の取得は省いてください。
関連API
X Thread Context API 以外に別の種類の公開Xデータが必要な場合は、これらのAPIをご利用ください。
- Twitter Tweet Scraper API — x.comまたはtwitter.comのステータスURLから、公開ポストのテキスト、投稿者、エンゲージメント、メディア、ハッシュタグ、メンション、会話の関係を取得します。
- Twitter User Tweets Scraper API — ユーザー名から、返信を除く最近の公開ポストを、投稿者、メディア、ハッシュタグ、メンション、エンゲージメントとともに取得します。
- X Post Quotes API — 既知のステータスURLについて公開引用ポストを取得し、コメント、投稿者、エンゲージメント、メディア、タイムスタンプ、元のポストの情報を返します。
- X Post Replies API — XのポストURLから公開返信を取得します。並び順を指定でき、返信テキスト、投稿者、表示中のエンゲージメント、メディア、親ポストの情報を返します。
- Twitter Mentions API — 指定したアカウントをメンションしている公開ポストを取得します。
- X Community Posts API — コミュニティで共有された公開ポストを、テキスト、投稿者、インタラクション数とともに取得します。
- Twitter Profile Scraper API
- Twitter Search API
- X Followers List API
- X Following List API
- X Post Retweeters API
- X Trends API
- Twitter User Search API
- X Community API
- X Account Location API
- X Verified Followers API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Communities Search API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API