x/
thread-context

Xポストのリンクから、そのポストの前後の文脈を取得します。対象ポスト、返信先となる以前のポスト、公開返信を、関係IDとあわせて返します。

X Thread Context API

ポストとその文脈
どのポストがどれに返信しているか
会話ごとのグループ化
結果1件あたり0.5クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

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を使って進行状況を確認し、結果を取得します。

  1. 文脈を知りたい公開ポストのリンクをコピーし、そのポストについてリクエストする文脈レコードの件数を決めます。リンクが複数ある場合は、それぞれを urls リストに入れてください。
  2. 例を実行する前に、$SOCQ_API_KEY をご自身のAPIキーに置き換えるか、その環境変数を設定してください。下記の Authorization ヘッダーを付けてJSON入力を POST /v1/x/thread-context に送信し、レスポンスの task_id を保存します。
  3. 保存したIDで GET /v1/tasks/{task_id} を呼び出して進行状況を確認します。queued は待機中、running は取得中、retrying は再試行中を意味します。結果を読み取る前に succeeded になるまで待ってください。タスクが failed になった場合は、error_message で理由を確認してください。
  4. タスクが成功したら data.results.items を読み取ります。このリストの各項目が1件のポストと、取得可能な会話の関係を表します。リストが空の場合は、タスクがレコードを返さずに完了したことを意味します。
  5. 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 を使用し、周辺の文脈の取得は省いてください。

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 — コミュニティで共有された公開ポストを、テキスト、投稿者、インタラクション数とともに取得します。

他のプラットフォームを見る

Xのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

X Thread Context API — よくある質問

X Thread Context APIは、Xポストのリンクから公開ディスカッションの文脈を取得するためのプログラムインターフェースです。対象ポスト、返信チェーンをさかのぼった以前のポスト、取得可能な返信、返されたポスト同士のつながりを示す関係IDを返します。

対象ポストは、送信したリンクのポストです。以前のポスト(祖先と呼ばれることもあります)は、対象ポストの返信関係を逆にたどってたどり着くメッセージであり、それより前に投稿されたすべてのポストではありません。

Aがポストを投稿し、BがAに返信した場合、Bの in_reply_to_id にはAのポストIDが入ります。conversation_id はポストを同じ会話にまとめ、in_reply_to_id は直接の返信先を示します。CがBに返信した場合、CはAではなくBを指します。

Thread Context には、返信に加えて、選んだポストと返信チェーンをさかのぼった公開の以前のポストが含まれます。X Post Replies は指定したポストへの返信に絞っているため、より範囲の狭い返信取得の用途に適しています。

できません。上限や公開範囲によって欠落が生じることがあり、関係IDが結果に含まれないポストを参照している場合もあります。欠けたメッセージやその意味を推測せず、取得できたつながりをそのまま保持してください。

いいえ。カーソルは、このタスクがすでに保存したレコードの別のページを読むものです。新しい取得を開始したり、元の取得上限を増やしたりするものではありません。

返されたポストレコード1件につき0.5クレジットで、基本料金はありません。リンクが2つで上限が100の場合、見積もりは100クレジットです。タスクが合計30件のポストを返した場合、最終的な料金は15クレジットです。