SocQを使えば、Twitter/Xのコミュニティの名前、説明、ルール、メンバー数とモデレーター数をプロフィール表にまとめられます。ソースと収集時刻を保存し、記録したコミュニティの情報に投稿を紐づけてレビューに活用できます。
SocQ X Community APIは、公開されているコミュニティのURLからメタデータを取得します。このガイドでは、リクエスト、返されるフィールド、ソースリンクと収集時刻付きのJSON・CSVエクスポートを説明します。
結論:
x.com/i/communities/{numeric_id}形式のリンクをurlsに入れて、POST /v1/x/communityに送信します。成功後、data.results.itemsから名前、説明、ルール、メンバー数とモデレーター数、参加ポリシーと招待ポリシーを読み取ります。投稿は、Community Postsで別途取得します。
コミュニティURLからプロフィール表を作る
コミュニティのURLを urls に入れると、名前、説明、ルール、メンバー数とモデレーター数、参加ポリシーと招待ポリシーを取得できます。この例では、Build in Publicコミュニティを使います。
https://x.com/i/communities/1493446837214187523
末尾の数字の部分がコミュニティIDです。urls には、/i/communities/{numeric_id} を含む完全なURLを指定してください。
名前から調べる場合は、まずそのコミュニティのURLを探します。レコードの照合にはコミュニティの数値IDを使い、名前が同じでもIDが異なるコミュニティは別々に管理してください。
| 知りたいこと | 使うもの |
|---|---|
| このコミュニティでどのメタデータを取得できるか | X Community |
| コミュニティからどの投稿を収集できるか | X Community Posts |
| 1つのディスカッション内の投稿がどう関連しているか | X Thread Context |
このエンドポイントが取得するのは、トピックコミュニティのメタデータです。コミュニティノートは投稿に付く注釈で、別のデータ種別です。
コミュニティ詳細をリクエストする
SOCQ_API_KEY を設定してから、URLを送信します。
curl -X POST "https://api.socq.ai/v1/x/community" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/i/communities/1493446837214187523"]}'
バッチで取得するには、公開コミュニティのリンクを urls に追加します。返される各レコードは1つのコミュニティを表します。件数は、実際に返されたレコードで数えてください。
data.task_id を TASK_ID として保存し、既存のタスクを照会します。
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
ステータスが queued、running、retrying の間は、間隔を空けて確認を続けます。succeeded になったら、data.results.items と保存されている残りの結果ページを読み取ります。タスクが失敗した場合は、data.error_message を確認します。タスクのページネーションは保存済みのデータを読み取るもので、コミュニティ情報を更新するものではありません。
ルール、人数、参加ポリシーを読み取る
次のメタデータの例では、一部のフィールドと、rules配列の中のルール1件を示しています。
{
"id": "1493446837214187523",
"type": "community",
"name": "Build in Public",
"metrics": {"members_count": 268858, "moderators_count": 6},
"join_policy": "Open",
"invites_policy": "MemberInvitesAllowed",
"rules": [
{
"id": "1493447542045958144",
"name": "Share what you're working on",
"description": "Don't be scared to share unfinished work"
}
],
"collected_at": "2026-10-15T08:12:58.252843Z"
}
text には説明、rules には構造化されたルール一覧、metrics には人数が格納されます。ルール名と説明は分けて保持し、ソースに説明がない場合はnullにしてください。
metrics.members_count はメンバーの合計数、metrics.moderators_count はモデレーターの合計数を記録します。収集時刻もあわせて保存しておくと、同じコミュニティの人数を取得時点ごとに比較できます。
join_policy と invites_policy には、参加ポリシーと招待ポリシーの元の文字列が格納されます。既知の値にラベルを付ける場合も元の値を残し、未知の値は返されたとおりに表示してください。実際に参加できるかどうかは、Xの最新のプロダクト画面で確認してください。
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")
エクスポート用のコードを、同じディレクトリに export_communities.py として保存します。
import csv
import json
from socq_collect import collect
urls = ["https://x.com/i/communities/1493446837214187523"]
task_id, items = collect("x/community", {"urls": urls})
with open("communities.json", "w", encoding="utf-8") as f:
json.dump({"task_id": task_id, "input": {"urls": urls}, "items": items},
f, ensure_ascii=False, indent=2)
fields = ["community_id", "url", "name", "description", "members_count",
"moderators_count", "join_policy", "invites_policy", "rules_json", "collected_at"]
def csv_cell(value):
if value is None:
return ""
if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
return "'" + value
return value
with open("communities.csv", "w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(f, fieldnames=fields)
writer.writeheader()
for item in items:
metrics = item.get("metrics") or {}
row = {"community_id": item.get("id"), "url": item.get("url"),
"name": item.get("name"), "description": item.get("text"),
"members_count": metrics.get("members_count"),
"moderators_count": metrics.get("moderators_count"),
"join_policy": item.get("join_policy"),
"invites_policy": item.get("invites_policy"),
"rules_json": json.dumps(item.get("rules"), ensure_ascii=False),
"collected_at": item.get("collected_at")}
writer.writerow({k: csv_cell(v) for k, v in row.items()})
python3 export_communities.py
JSONには、標準形式の生レコードと送信したリンクが保持されます。CSVには、返されたコミュニティごとにレビュー用の行が1つ作られ、ルールはJSONとしてシリアライズされるため、カンマや改行で構造が崩れません。rules_json=null と空のリストは区別できます。数式のように見える公開テキストのエスケープはCSVでのみ行われ、識別子はテキストとしてインポートしてください。
入力に対してメタデータが返らなかった場合は、空の結果とその照会時刻を別に記録します。以前に保存したメタデータは、履歴の比較用に元の収集時刻のまま保持してください。
コミュニティのメタデータを収集した投稿とつなぐ
ディスカッションが必要な場合は、確認済みの同じコミュニティURLをX Community Postsで使います。これは別のタスクとして開始され、結果の上限も別になります。コミュニティ投稿のチュートリアルでは、投稿をエクスポートする際に入力元のコミュニティを保持する方法を紹介しています。
コミュニティID、ソースURL、タスクID、収集時刻をメタデータとあわせて保存します。収集した各投稿に入力元のコミュニティを付与しておけば、プロフィール表と投稿表をコミュニティIDで結合できます。
説明、ルール、収集した投稿は、それぞれの収集時刻とあわせて確認してください。投稿の返信関係については、スレッドコンテキストのチュートリアルに進んでください。
コミュニティのメタデータを再利用できるリサーチ資産にする
SocQは、コミュニティのメタデータを標準フィールドに整理します。コードを使ってプロフィール表と構造化されたルールを保存し、収集した投稿をコミュニティIDで結合できます。説明、ルール、ディスカッションが明確なソースを共有するため、リサーチ用ファイル、サンプルのレビュー、日付付きの更新に活用できます。
よくある質問(FAQ)
Twitter Community APIは何を返しますか?
コミュニティの名前、説明、ルール、メンバー数とモデレーター数、参加ポリシー、招待ポリシーを返します。フィールドの定義と課金については、X Community APIのページを参照してください。
コミュニティ移行の発表後、メタデータはどう取得すればよいですか?
Xは、コミュニティからXChatへの移行に関する発表を公開しました。メタデータの取得には対象のコミュニティURLを使います。タスクが成功したら返されたレコードを読み取り、空の結果の場合は照会時刻を保存し、失敗した場合はエラーの詳細を確認してください。参加や投稿に関する機能は、Xの最新の画面で確認してください。
コミュニティを名前で検索できますか?
取得にはコミュニティURLを使います。名前に対応するリンクを確認してから、urls に指定してください。
メンバー数には、メンバーやモデレーターの一覧が含まれますか?
レスポンスに含まれるのは、メンバーとモデレーターの合計数のみです。個々のアカウントの一覧は別のデータで、このメタデータのレスポンスには含まれません。
Openポリシーなら、今すぐ参加できますか?
Open は、メタデータで返される参加ポリシーの値です。現在の参加可否はXの画面で確認してください。このエンドポイントが読み取るのはメタデータです。
コミュニティの投稿やコミュニティノートは含まれますか?
コミュニティの投稿は、X Community Postsで取得します。コミュニティノートは別の投稿への注釈です。このエンドポイントが返すのは、コミュニティのメタデータです。
この人数でコミュニティの活発さをランキングできますか?
メンバー数とモデレーター数は規模を示すものです。活発さを調べるには、投稿を収集し、アプリケーション側で published_at を使って期間を選び、そのサンプル内の投稿数、投稿者数、インタラクション数を数えてください。