Utilisez SocQ pour organiser dans un tableau de profils les noms, les descriptions, les règles et les nombres de membres et de modérateurs des communautés Twitter/X. Enregistrez les sources et les dates de capture, puis reliez les posts au contexte de communauté enregistré pour les examiner.
SocQ X Community API interroge les métadonnées à partir de l’URL publique d’une communauté. Ce guide couvre les requêtes, les champs renvoyés et les exports JSON et CSV avec liens sources et dates de collecte.
Réponse rapide : placez des liens
x.com/i/communities/{numeric_id}dansurlset envoyez-les àPOST /v1/x/community. Une fois la tâche terminée, lisez dansdata.results.itemsles noms, les descriptions, les règles, les nombres de membres et de modérateurs, ainsi que les politiques d’adhésion et d’invitation. Interrogez les posts séparément avec Community Posts.
Construire un tableau de profils à partir d’URL de communautés
Placez l’URL d’une communauté dans urls pour interroger son nom, sa description, ses règles, ses nombres de membres et de modérateurs, ainsi que ses politiques d’adhésion et d’invitation. Cet exemple utilise la communauté Build in Public :
https://x.com/i/communities/1493446837214187523
Le dernier segment numérique est l’identifiant de la communauté. Fournissez dans urls l’URL complète /i/communities/{numeric_id}.
Si vous partez d’un nom, trouvez d’abord l’URL de la communauté. Rapprochez les enregistrements par identifiant numérique de communauté et gardez séparées les communautés dont les identifiants diffèrent, même lorsque leurs noms sont identiques.
| Question | À utiliser |
|---|---|
| Quelles métadonnées sont disponibles pour cette communauté ? | X Community |
| Quels posts puis-je collecter dans la communauté ? | X Community Posts |
| Comment les posts d’une même discussion sont-ils liés ? | X Thread Context |
Cet endpoint interroge les métadonnées des communautés thématiques. Les Community Notes sont des annotations rattachées aux posts et constituent un type de données distinct.
Demander les détails d’une communauté
Définissez SOCQ_API_KEY, puis envoyez l’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"]}'
Pour un lot, ajoutez des liens de communautés publiques à urls. Chaque enregistrement renvoyé décrit une communauté ; comptez les résultats d’après les enregistrements réellement renvoyés.
Enregistrez data.task_id sous le nom TASK_ID, puis interrogez la tâche existante :
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Patientez entre deux vérifications tant que le statut est queued, running ou retrying. Une fois le statut succeeded, lisez data.results.items et les éventuelles pages de résultats stockées restantes. Si la tâche échoue, examinez data.error_message. La pagination d’une tâche lit des données enregistrées ; elle n’actualise pas les informations de la communauté.
Lire les règles, les compteurs et les politiques d’adhésion
Cet exemple de métadonnées montre quelques champs et une règle du tableau de règles :
{
"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 contient la description, rules la liste structurée des règles et metrics les compteurs. Gardez séparés le nom et la description de chaque règle, avec null pour les descriptions omises par la source.
metrics.members_count enregistre le nombre total de membres et metrics.moderators_count celui des modérateurs. Conservez leurs dates de collecte pour comparer les compteurs d’une même communauté d’une capture à l’autre.
join_policy et invites_policy stockent les chaînes d’origine des politiques d’adhésion et d’invitation. Conservez la valeur d’origine lorsque vous étiquetez une valeur connue, et affichez telles quelles les valeurs inconnues. Vérifiez l’accès réel à l’adhésion dans l’interface actuelle de X.
Exporter un tableau de profils de communautés avec Python
Enregistrez cet utilitaire de tâches, qui n’utilise que la bibliothèque standard, sous le nom 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")
Enregistrez l’exporteur sous le nom export_communities.py dans le même répertoire :
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
Le JSON conserve les enregistrements standard bruts et les liens envoyés. Le CSV fournit une ligne de revue par communauté renvoyée, avec les règles sérialisées en JSON afin que les virgules et les sauts de ligne ne détruisent pas leur structure. rules_json=null reste distinguable d’une liste vide. Le texte public qui ressemble à une formule n’est échappé que dans le CSV, et les identifiants doivent être importés comme du texte.
Lorsqu’une entrée ne renvoie aucune métadonnée, consignez séparément le résultat vide et sa date d’interrogation. Conservez les métadonnées déjà enregistrées avec leur date de collecte d’origine pour les comparaisons historiques.
Relier les métadonnées de communauté aux posts collectés
Utilisez la même URL de communauté confirmée avec X Community Posts lorsque vous avez besoin des discussions. Cela lance une tâche distincte, avec son propre plafond de résultats. Le tutoriel sur les posts de communauté montre comment conserver la communauté source de l’entrée lors de l’export des posts.
Enregistrez avec les métadonnées l’identifiant de la communauté, l’URL source, l’ID de tâche et la date de collecte. Rattachez la communauté d’entrée à chaque post collecté afin de pouvoir joindre les tableaux de profils et de posts par identifiant de communauté.
Examinez ensemble la description, les règles et les posts collectés, avec leurs dates de capture respectives. Pour les relations de réponse d’un post, poursuivez avec le tutoriel sur le contexte de fil.
Faire des métadonnées de communauté une ressource de recherche réutilisable
SocQ organise les métadonnées de communauté en champs standard. Utilisez le code pour enregistrer un tableau de profils et des règles structurées, puis joignez les posts collectés par identifiant de communauté. Les descriptions, les règles et les discussions partagent une source explicite pour les fichiers de recherche, les revues d’échantillons et les mises à jour datées.
Ouvrir X Community et interroger votre URL source.
FAQ
Que renvoie la Twitter Community API ?
Les noms, les descriptions, les règles, les nombres de membres et de modérateurs, ainsi que les politiques d’adhésion et d’invitation des communautés. Consultez la page X Community API pour les définitions des champs et la facturation.
Comment interroger les métadonnées après l’annonce de migration des communautés ?
X a publié une annonce de migration de Communities vers XChat. Utilisez l’URL de la communauté cible pour la recherche de métadonnées : lisez les enregistrements renvoyés une fois la tâche terminée, enregistrez la date d’interrogation en cas de résultat vide et examinez les détails de l’erreur en cas d’échec. Vérifiez les fonctionnalités d’adhésion et de participation dans l’interface actuelle de X.
Peut-on rechercher une communauté par son nom ?
La recherche prend des URL de communautés. Confirmez le lien associé au nom, puis envoyez-le dans urls.
Le nombre de membres inclut-il une liste de membres ou de modérateurs ?
La réponse contient les nombres agrégés de membres et de modérateurs. Les annuaires de comptes individuels sont des données distinctes et ne font pas partie de cette réponse de métadonnées.
Une politique Open signifie-t-elle que je peux rejoindre la communauté maintenant ?
Open est la valeur de politique d’adhésion renvoyée dans les métadonnées. Vérifiez l’accès actuel à l’adhésion dans l’interface de X ; cet endpoint lit les métadonnées.
Les posts de communauté ou les Community Notes sont-ils inclus ?
Interrogez les posts de communauté avec X Community Posts. Les Community Notes sont des annotations de posts distinctes. Cet endpoint renvoie les métadonnées de communauté.
Puis-je utiliser ces compteurs pour classer l’activité des communautés ?
Les totaux de membres et de modérateurs décrivent l’échelle. Pour étudier l’activité, collectez des posts, sélectionnez une période à l’aide de published_at dans votre application et comptez les posts, les auteurs ou les interactions dans cet échantillon.
X API
Tester le workflow avec une URL publique X
Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.
Découvrir les API X