Используйте 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 полный URL вида /i/communities/{numeric_id}.
Если у вас есть только название, сначала найдите URL сообщества. Сопоставляйте записи по числовому ID сообщества и храните сообщества с разными ID отдельно, даже если их названия совпадают.
| Вопрос | Что использовать |
|---|---|
| Какие метаданные доступны для этого сообщества? | X Community |
| Какие посты можно собрать из сообщества? | X Community Posts |
| Как связаны посты в одном обсуждении? | X Thread Context |
Этот эндпоинт запрашивает метаданные тематических сообществ. Community Notes — это пометки к постам, отдельный тип данных.
Запрос данных о сообществе
Задайте 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. Каждая возвращенная запись описывает одно сообщество; считайте результаты по фактически возвращенным записям.
Сохраните 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. Пагинация задачи читает сохраненные данные и не обновляет информацию о сообществе.
Правила, счетчики и политики вступления
В этом примере метаданных показаны отдельные поля и одно правило из массива правил:
{
"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 дает по одной строке для проверки на каждое возвращенное сообщество, а правила сериализуются в JSON, чтобы запятые и переносы строк не нарушали их структуру. rules_json=null остается отличимым от пустого списка. Публичный текст, похожий на формулы, экранируется только в CSV, а идентификаторы следует импортировать как текст.
Если по входным данным метаданные не вернулись, отдельно зафиксируйте пустой результат и время запроса. Ранее сохраненные метаданные храните с исходным временем сбора для исторического сравнения.
Связь метаданных сообщества с собранными постами
Когда нужны обсуждения, используйте тот же подтвержденный URL сообщества с X Community Posts. Это запускает отдельную задачу с отдельным лимитом результатов. В руководстве по постам сообществ показано, как сохранять источник — входное сообщество — при выгрузке постов.
Сохраняйте вместе с метаданными ID сообщества, исходный URL, ID задачи и время сбора. Привязывайте входное сообщество к каждому собранному посту, чтобы таблицы профилей и постов можно было объединить по ID сообщества.
Анализируйте описание, правила и собранные посты вместе, с учетом времени их сбора. Для связей ответов к посту переходите к руководству по контексту обсуждения.
Метаданные сообществ как переиспользуемый ресурс для исследований
SocQ раскладывает метаданные сообществ по стандартным полям. С помощью кода сохраняйте таблицу профилей и структурированные правила, затем объединяйте собранные посты по ID сообщества. У описаний, правил и обсуждений появляется явный общий источник для исследовательских материалов, проверки выборок и датированных обновлений.
Откройте X Community и запросите свой исходный URL.
FAQ
Что возвращает Twitter Community API?
Названия сообществ, описания, правила, число участников и модераторов, политики вступления и политики приглашений. Определения полей и тарификацию см. на странице X Community API.
Как запрашивать метаданные после объявления о миграции сообществ?
X опубликовала объявление о переносе сообществ в XChat. Для получения метаданных используйте URL целевого сообщества: после успешного выполнения задачи читайте возвращенные записи, для пустых результатов сохраняйте время запроса, а при сбое изучайте сведения об ошибке. Возможности вступления и участия проверяйте в текущем интерфейсе X.
Можно ли найти сообщество по названию?
Запрос принимает URL сообществ. Подтвердите ссылку, связанную с названием, затем передайте ее в urls.
Включает ли число участников список участников или модераторов?
Ответ содержит агрегированное число участников и модераторов. Списки отдельных аккаунтов — это другие данные, и в этот ответ с метаданными они не входят.
Означает ли политика Open, что можно вступить прямо сейчас?
Open — значение политики вступления, возвращенное в метаданных. Текущую возможность вступить проверяйте в интерфейсе X; этот эндпоинт читает метаданные.
Входят ли в ответ посты сообщества или Community Notes?
Посты сообщества запрашивайте через X Community Posts. Community Notes — отдельные пометки к постам. Этот эндпоинт возвращает метаданные сообщества.
Можно ли по этим счетчикам ранжировать активность сообществ?
Общее число участников и модераторов описывает масштаб. Чтобы изучить активность, соберите посты, выберите период по published_at в своем приложении и посчитайте посты, авторов или взаимодействия в этой выборке.
X API
Проверить сценарий на публичном URL X
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для X