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 | 現在の投稿の識別子 | 投稿のインデックス作成と重複排除に使う |
次の説明用のデータで、関係を確認します。
| 投稿 | 投稿者 | 会話 | 直接の親 |
|---|---|---|---|
| A | Alice | A | なし |
| B | Alice | A | A |
| C | Bob | A | B |
| D | Alice | A | C |
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を同じ標準の結果にまとめます。コードを使って、会話のグループ化、返信関係のエクスポート、投稿者で絞り込んだビューの作成ができます。閲覧用のインターフェースや要約ワークフローは、これらのレコードを、取得元と文脈の欠落マーカーとあわせて再利用できます。
参考資料
- SocQ Thread Contextのドキュメント — 公開入力、上限、標準の関係フィールド。
よくある質問(FAQ)
最初の投稿ではなく、返信から始められますか?
はい。その公開された返信のURLをurlsに指定してください。タスクは、対象の投稿、公開されているそれ以前の投稿、取得元が返す返信を、設定した上限まで読み取ります。
投稿への返信を取得するのと同じですか?
Post Repliesは、選択した投稿への返信を対象にします。Thread Contextは、対象の投稿、それ以前の投稿、返信を読み取り、返信の関係を通じて文脈を整理します。
APIは会話内のすべての返信を返しますか?
タスクは、各入力のresults_limitまでの公開レコードを収集します。すべてのページを読み取れば、その取得で保存された投稿を取得できます。議論のカバー範囲は、親の欠落と返信のレコードもあわせて評価してください。
返信への返信はどう扱えばよいですか?
in_reply_to_idで直接の親を結び付け、conversation_idで会話をグループ化します。親が欠けている場合はそのIDを保持し、欠落マーカーを表示してください。
参照されている親投稿がないのはなぜですか?
親への参照は返されたものの、その本文がこの取得結果に含まれていません。参照を残し、さらに文脈が必要なときにその投稿を問い合わせてください。欠落している具体的な理由は、取得元が報告する情報をもとに判断してください。
元の投稿者のスレッドだけを残すにはどうすればよいですか?
投稿者IDを確認し、親と子の両方がその投稿者に属するエッジを残します。対象の投稿を中心につながった区間を選び、自己返信が枝分かれする場合は表示範囲を選んでください。
スレッドをAIによる要約用に保存できますか?
はい。収集したテキスト、投稿者、時刻、関係をJSONとして保存し、別の要約ステップを実行します。要約と一緒に、文脈の欠落マーカーと取得元URLも残してください。