XTwitterスレッドネストされた返信会話IDAPIチュートリアル

Twitter Thread API:スレッドの文脈とネストされた返信を取得する方法

SocQでTwitter/Xのスレッドの文脈を取得します。Pythonのコードで会話をグループ化し、返信を結び付け、投稿者のスレッドを絞り込んで、確認用のJSONにエクスポートします。

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

SocQを使うと、対象の投稿、それ以前の文脈、返信の関係をまとめて取得できます。Twitter/Xの議論を「誰が誰に返信したか」で整理し、会話IDと直接の親投稿のIDを使って、閲覧、レビュー、要約、投稿者のスレッドの絞り込みに活用できます。

SocQ X Thread Context APIは、対象の公開投稿、返信チェーンのそれ以前の投稿、取得元が返す返信を取得します。このガイドでは、データ収集、会話のグループ化、親子関係のエクスポート、投稿者のスレッドの絞り込みを説明します。

要点: 公開投稿のURLをPOST /v1/x/thread-contextに送信し、完了したタスクの結果ページを読み取ります。conversation_idでグループ化し、in_reply_to_idで直接の親投稿を結び付けます。親投稿の本文がない場合は、その参照を残して欠落として記録します。

投稿の取得、返信、Thread Contextの使い分け

必要なデータSocQのエンドポイント最初の入力
選択した投稿そのものX Posts公開投稿のURL
選択した投稿への返信X Post Replies公開投稿のURL
対象の投稿、返信チェーンのそれ以前の投稿、取得できる返信X Thread Context公開投稿のURL
コミュニティ内で共有された投稿X Community Posts公開コミュニティのURL

選択した投稿より前の議論を読むには、Thread Contextを使います。「それ以前の投稿」とは、直接の親投稿の関係をさかのぼってたどり着く投稿のことです。

たとえば、BがAに返信し、CがBに返信した場合、Cの親チェーンはC → B → Aです。グループ化は会話IDで、つながりは親投稿のIDで決まり、表示する際の時系列順は投稿時刻で決まります。

収集した後は、テキストと関係データを閲覧用のインターフェースや、別の要約ワークフローに渡します。

公開投稿のURLからThread Contextを取得する

公開された/status/{numeric_id}形式のURLを使い、例の部分を調べたい投稿に置き換えてください。

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": 100
  }'

入力には、XとTwitterの公開投稿リンクを指定でき、議論の途中にある返信も指定できます。urlsには、/status/{numeric_id}を含む完全なURLを入れてください。

レスポンスのdata.task_idが、バックグラウンドのタスクを識別します。これを保存して、次のようにリクエストします。

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

タスクがqueued、running、retryingの間は待機します。failedの場合はdata.error_messageを確認してください。succeededになったらdata.results.itemsを読み取り、has_moreがtrueの間はnext_cursorで続きを取得します。

results_limitのデフォルトは100で、入力URLごとに1〜2000の整数を指定できます。上限を100にした2つのURLは、それぞれ独立して最大100レコードをリクエストします。同じ会話の取得結果を統合するときは、投稿IDで重複を排除してください。

Thread Contextは、この範囲内であればどの整数でも受け付けます。取得後は、関係を表すフィールドから親子のつながりを組み立て、レコードの処理には配列の順序を使ってください。

会話IDと親投稿IDを理解する

2つの関係フィールドは、それぞれ異なる目的で使います。

フィールド意味処理
conversation_idその投稿が属する会話同じ値のレコードをグループ化する
in_reply_to_id直接の親投稿のIDそのIDを検索して投稿を結び付ける
id現在の投稿の識別子投稿のインデックス作成と重複排除に使う

次の説明用のデータで、関係を確認します。

投稿投稿者会話直接の親
AAliceAなし
BAliceAA
CBobAB
DAliceAC

4つの投稿はすべて会話Aに属し、Dの直接の親はCです。親IDでつなげると、D → C → B → Aという返信の経路が保たれます。

各フィールドの定義は、Thread Contextのフィールドリファレンスをご覧ください。グループ化には会話ID、結び付けには直接の親IDと、それぞれの手順で使い分けます。

標準のレコードには、テキスト、投稿者、投稿時刻と収集時刻、メディア、エンゲージメント数も含まれます。取得元が省略したフィールドはnullのままです。

Pythonで保存済みの結果ページを収集する

次の標準ライブラリだけで書いたヘルパーを、socq_collect.pyとして保存します。

import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}

def api(method, path, payload=None):
    body = json.dumps(payload).encode("utf-8") if payload is not None else None
    request = Request(
        BASE + path, data=body, method=method,
        headers={
            "Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    if result.get("code") != 200:
        raise RuntimeError(result)
    return result["data"]

def collect(endpoint, payload):
    task_id = api("POST", "/" + endpoint, payload)["task_id"]
    print("Task:", task_id, flush=True)
    path = "/tasks/" + task_id
    deadline = time.monotonic() + 600
    data = api("GET", path + "?limit=100")
    while data["status"] in PENDING:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
        time.sleep(2)
        data = api("GET", path + "?limit=100")
    if data["status"] != "succeeded":
        raise RuntimeError(data.get("error_message") or data["status"])

    items, seen_cursors = [], set()
    while True:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume pagination for " + task_id)
        page = data["results"]
        items.extend(page["items"])
        if not page["has_more"]:
            return task_id, items
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated result cursor")
        seen_cursors.add(cursor)
        data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
        if data["status"] != "succeeded":
            raise RuntimeError("Task is not ready for result pagination")

次のスクリプトを、同じディレクトリにcollect_thread.pyとして保存します。

import json
import sys
from socq_collect import collect

if len(sys.argv) != 2:
    raise SystemExit("Usage: python3 collect_thread.py PUBLIC_POST_URL")
payload = {"urls": [sys.argv[1]], "results_limit": 100}
task_id, posts = collect("x/thread-context", payload)
with open("thread-context.json", "w", encoding="utf-8") as output:
    json.dump({"task_id": task_id, "input": payload, "items": posts},
              output, ensure_ascii=False, indent=2)

SOCQ_API_KEYを設定し、選んだ公開投稿を指定して実行します。

python3 collect_thread.py \
  "https://x.com/BaganiTohid/status/2110635249889919362"

thread-context.jsonには、入力リンク、タスクID、レコードが保存されます。ヘルパーはクライアント側で最大10分間待機します。タイムアウトした場合は、表示されたタスクIDを控えておき、サーバー側のタスクの確認を続けてください。

ページネーションでは、そのタスクが保存したレコードを読み取ります。すべてのページを読み取れば、保存された結果セットを完全に取得できます。レコードと欠落マーカーが、会話のカバー範囲を示します。

直接の親IDで返信の関係を組み立てる

投稿をIDでインデックス化してから、親子のリンクを追加します。参照されている親投稿の本文がない場合は、IDを残してparent_in_datasetをfalseにします。

次のスクリプトをbuild_thread.pyとして保存します。

import json
import sys

if len(sys.argv) not in (2, 3):
    raise SystemExit("Usage: python3 build_thread.py INPUT_JSON [THREAD_AUTHOR_ID]")
with open(sys.argv[1], encoding="utf-8") as source:
    records = json.load(source)["items"]
author_id = sys.argv[2] if len(sys.argv) == 3 else None

nodes, missing_id_records = {}, []
for post in records:
    if post.get("id"):
        nodes[str(post["id"])] = post
    else:
        missing_id_records.append(post)

edges, groups, unknown_conversation_ids, unknown_parent_ids = [], {}, [], []
for post_id, post in nodes.items():
    conversation_id = post.get("conversation_id")
    if conversation_id:
        groups.setdefault(str(conversation_id), []).append(post_id)
    else:
        unknown_conversation_ids.append(post_id)
    parent_id = post.get("in_reply_to_id")
    if parent_id is None:
        unknown_parent_ids.append(post_id)
    else:
        parent_id = str(parent_id)
        edges.append({
            "parent_id": parent_id, "child_id": post_id,
            "parent_in_dataset": parent_id in nodes,
        })

self_reply_edges = []
if author_id:
    for edge in edges:
        parent = nodes.get(edge["parent_id"])
        child = nodes[edge["child_id"]]
        if parent and edge["parent_id"] != edge["child_id"]:
            parent_author = (parent.get("author") or {}).get("id")
            child_author = (child.get("author") or {}).get("id")
            if parent_author == author_id and child_author == author_id:
                self_reply_edges.append(edge)

graph = {
    "nodes": list(nodes.values()), "edges": edges, "conversation_groups": groups,
    "missing_parent_ids": sorted({
        edge["parent_id"] for edge in edges if not edge["parent_in_dataset"]
    }),
    "unknown_conversation_post_ids": unknown_conversation_ids,
    "unknown_parent_post_ids": unknown_parent_ids,
    "records_without_id": missing_id_records,
    "selected_author_id": author_id, "selected_author_self_reply_edges": self_reply_edges,
}
with open("thread-graph.json", "w", encoding="utf-8") as output:
    json.dump(graph, output, ensure_ascii=False, indent=2)

関係のエクスポートを作成します。

python3 build_thread.py thread-context.json

生成されるthread-graph.jsonには、次の内容が含まれます。

  • 識別できる一意の投稿ノード。IDのないレコードは別に保持されます。
  • 親が存在するかどうかをparent_in_datasetで示す、親子のエッジ。
  • 会話IDが判明しているもののグループと、会話IDが欠けているものの別リスト。
  • 対応する収集済みの投稿がない、参照された親ID。
  • 直接の親フィールドがnullの投稿ID。

in_reply_to_id=nullは、そのレコードが直接の親への参照を持たないことを意味します。プログラムは、これをunknown_parent_post_idsに追加します。親IDはあるのにそのレコードがインデックスにない場合は、エッジを残して、親が欠けていることを記録してください。

このエクスポートでは、会話のグループ、判明している関係のエッジ、レコードの欠落マーカーが保持されます。閲覧用のインターフェースでは、つながった枝と文脈の欠落部分を分けて表示できます。

投稿者のスレッドと読者の返信を分ける

説明用のデータでは、AliceがA、B、Dを書いています。AからBは投稿者による自己返信の区間で、DはBobへのAliceの返信です。投稿者のIDで絞り込めば、その投稿者のすべての発言を読めます。自己返信の区間を特定するには、親と子の両方の投稿者IDを確認します。

スレッドの投稿者のアカウントIDがわかっている場合は、その文字列を第2引数に渡します。

python3 build_thread.py thread-context.json THREAD_AUTHOR_ID

selected_author_self_reply_edgesには、親と子の両方が指定した投稿者に属するエッジが保存されます。絞り込む前に、その投稿者IDを確認してください。入力リンクは、投稿者自身の投稿を指す場合も、読者の返信を指す場合もあります。

読みたい投稿者の投稿を中心に、つながった自己返信の区間を選択します。投稿者が1つの親に対して複数の自己返信をしている場合、エクスポートはそれらの枝を保持するため、閲覧用のインターフェース側で表示範囲を選べます。

完全なレコードと、投稿者で絞り込んだビューを一緒に保管しておくと、後から別の閲覧用フィルターを元のデータで作れます。

閲覧、レビュー、要約のために文脈をエクスポートする

閲覧用のインターフェースには、取得元URL、投稿者、投稿時刻、親子の関係を表示し、親が欠けている箇所にはマーカーを付けます。関係を表すJSONは、テキストやMarkdownのエクスポートと一緒に保存しておくと、後から構造を再構築できます。

要約ワークフローでは、投稿のテキストと関係を読み取り、投稿者の発言と読者の反応を分けて扱い、文脈の欠落マーカーを保持します。Thread Contextが提供するのはレコードであり、要約は自分のモデルやアプリケーションが生成します。

同じ会話のタスクを統合する場合は、投稿IDで重複を排除し、入力リンクとタスクIDを保持してください。以前に観測した投稿が後の取得結果に含まれなくなった場合も、元の取得時刻のまま残します。

調べる前に議論を探したい場合は、コミュニティ収集のチュートリアルやXの検索・収集ガイドをご利用ください。

閲覧、レビュー、要約に使える1つの文脈データセット

SocQのThread Contextは、投稿のテキストと関係IDを同じ標準の結果にまとめます。コードを使って、会話のグループ化、返信関係のエクスポート、投稿者で絞り込んだビューの作成ができます。閲覧用のインターフェースや要約ワークフローは、これらのレコードを、取得元と文脈の欠落マーカーとあわせて再利用できます。

Thread Contextを開いて、調べたい議論を試す。

参考資料

よくある質問(FAQ)

最初の投稿ではなく、返信から始められますか?

はい。その公開された返信のURLをurlsに指定してください。タスクは、対象の投稿、公開されているそれ以前の投稿、取得元が返す返信を、設定した上限まで読み取ります。

投稿への返信を取得するのと同じですか?

Post Repliesは、選択した投稿への返信を対象にします。Thread Contextは、対象の投稿、それ以前の投稿、返信を読み取り、返信の関係を通じて文脈を整理します。

APIは会話内のすべての返信を返しますか?

タスクは、各入力のresults_limitまでの公開レコードを収集します。すべてのページを読み取れば、その取得で保存された投稿を取得できます。議論のカバー範囲は、親の欠落と返信のレコードもあわせて評価してください。

返信への返信はどう扱えばよいですか?

in_reply_to_idで直接の親を結び付け、conversation_idで会話をグループ化します。親が欠けている場合はそのIDを保持し、欠落マーカーを表示してください。

参照されている親投稿がないのはなぜですか?

親への参照は返されたものの、その本文がこの取得結果に含まれていません。参照を残し、さらに文脈が必要なときにその投稿を問い合わせてください。欠落している具体的な理由は、取得元が報告する情報をもとに判断してください。

元の投稿者のスレッドだけを残すにはどうすればよいですか?

投稿者IDを確認し、親と子の両方がその投稿者に属するエッジを残します。対象の投稿を中心につながった区間を選び、自己返信が枝分かれする場合は表示範囲を選んでください。

スレッドをAIによる要約用に保存できますか?

はい。収集したテキスト、投稿者、時刻、関係をJSONとして保存し、別の要約ステップを実行します。要約と一緒に、文脈の欠落マーカーと取得元URLも残してください。

X API

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

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

XのAPIを見る