Usa SocQ per organizzare in una tabella dei profili i nomi, le descrizioni, le regole e il numero di membri e moderatori delle community di Twitter/X. Salva le fonti e gli orari di raccolta, poi collega i post al contesto registrato della community per la revisione.
La X Community API di SocQ interroga i metadati a partire dall’URL pubblico della community. Questa guida copre le richieste, i campi restituiti e le esportazioni in JSON e CSV con link di origine e orari di raccolta.
Risposta rapida: inserisci i link
x.com/i/communities/{numeric_id}inurlse invia la richiesta aPOST /v1/x/community. Dopo il completamento, leggi dadata.results.itemsnomi, descrizioni, regole, numero di membri e moderatori e criteri di adesione e di invito. I post si interrogano a parte con Community Posts.
Creare una tabella dei profili a partire dagli URL delle community
Inserisci l’URL di una community in urls per interrogarne nome, descrizione, regole, numero di membri e moderatori e criteri di adesione e di invito. Questo esempio usa la community Build in Public:
https://x.com/i/communities/1493446837214187523
L’ultimo segmento numerico è l’ID della community. Fornisci in urls l’URL completo /i/communities/{numeric_id}.
Se parti da un nome, trova prima l’URL della community. Associa i record tramite l’ID numerico della community e tieni separate le community con ID diversi anche quando i nomi coincidono.
| Domanda | Cosa usare |
|---|---|
| Quali metadati sono disponibili per questa community? | X Community |
| Quali post posso raccogliere dalla community? | X Community Posts |
| Come sono collegati i post di una stessa discussione? | X Thread Context |
Questo endpoint interroga i metadati delle community tematiche. Le Community Notes sono annotazioni associate ai post e costituiscono un tipo di dati a parte.
Richiedere i dettagli della community
Imposta SOCQ_API_KEY, poi invia 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"]}'
Per un batch, aggiungi a urls altri link pubblici di community. Ogni record restituito descrive una community: conta i risultati in base ai record effettivamente restituiti.
Salva data.task_id come TASK_ID, poi interroga l’attività esistente:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Attendi tra un controllo e l’altro finché lo stato è queued, running o retrying. Dopo succeeded, leggi data.results.items e le eventuali altre pagine di risultati salvate. Se l’attività fallisce, controlla data.error_message. La paginazione dell’attività legge dati già salvati e non aggiorna le informazioni sulla community.
Leggere regole, conteggi e criteri di adesione
Questo esempio di metadati mostra alcuni campi selezionati e una regola dell’array delle regole:
{
"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 contiene la descrizione, rules l’elenco strutturato delle regole e metrics i conteggi. Tieni separati nomi e descrizioni delle regole, con null per le descrizioni omesse dalla fonte.
metrics.members_count registra il totale dei membri e metrics.moderators_count il totale dei moderatori. Salva gli orari di raccolta per confrontare i conteggi della stessa community tra acquisizioni diverse.
join_policy e invites_policy conservano le stringhe originali dei criteri di adesione e di invito. Conserva il valore originale quando assegni un’etichetta a un valore noto e mostra i valori sconosciuti così come sono restituiti. Verifica l’effettivo accesso alla community nell’interfaccia attuale del prodotto di X.
Esportare una tabella dei profili delle community con Python
Salva questo helper per le attività, basato sulla libreria standard, come 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")
Salva lo script di esportazione come export_communities.py nella stessa directory:
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
Il JSON conserva i record standard grezzi e i link inviati. Il CSV fornisce una riga di revisione per ogni community restituita, con le regole serializzate come JSON, così virgole e ritorni a capo non ne rovinano la struttura. rules_json=null resta distinguibile da un elenco vuoto. Il testo pubblico che sembra una formula viene sottoposto a escape solo nel CSV e gli identificatori vanno importati come testo.
Quando un input non restituisce metadati, registra a parte il risultato vuoto e l’orario della richiesta. Conserva i metadati già salvati con il loro orario di raccolta originale per i confronti storici.
Collegare i metadati delle community ai post raccolti
Usa lo stesso URL di community confermato con X Community Posts quando ti servono le discussioni. Questo avvia un’attività separata, con un limite di risultati separato. Il tutorial sui post delle community mostra come conservare la community di origine dell’input durante l’esportazione dei post.
Salva insieme ai metadati ID della community, URL di origine, ID attività e orario di raccolta. Associa la community di input a ogni post raccolto, in modo che le tabelle dei profili e dei post possano essere unite tramite l’ID della community.
Esamina insieme descrizione, regole e post raccolti, tenendo conto dei rispettivi orari di acquisizione. Per le relazioni tra le risposte a un post, continua con il tutorial sul contesto dei thread.
Rendere i metadati delle community una risorsa di ricerca riutilizzabile
SocQ organizza i metadati delle community in campi standard. Usa il codice per salvare una tabella dei profili e le regole strutturate, poi unisci i post raccolti tramite l’ID della community. Descrizioni, regole e discussioni condividono una fonte esplicita per file di ricerca, revisioni a campione e aggiornamenti datati.
Apri X Community e interroga il tuo URL di origine.
Domande frequenti (FAQ)
Cosa restituisce la Twitter Community API?
Nomi, descrizioni, regole, numero di membri e moderatori, criteri di adesione e criteri di invito delle community. Nella pagina della X Community API trovi le definizioni dei campi e la fatturazione.
Come interrogo i metadati dopo l’annuncio della migrazione delle community?
X ha pubblicato un annuncio sulla migrazione da Communities a XChat. Usa l’URL della community di destinazione per la ricerca dei metadati: leggi i record restituiti dopo il completamento dell’attività, salva l’orario della richiesta per i risultati vuoti e controlla i dettagli dell’errore in caso di fallimento. Verifica le funzioni di adesione e partecipazione nell’interfaccia attuale di X.
Posso cercare una community per nome?
La ricerca accetta URL di community. Conferma il link associato al nome, poi invialo in urls.
Il numero di membri comprende un elenco dei membri o dei moderatori?
La risposta contiene i conteggi aggregati di membri e moderatori. Gli elenchi dei singoli account sono dati separati e non fanno parte di questa risposta di metadati.
Un criterio Open significa che posso iscrivermi subito?
Open è il valore del criterio di adesione restituito nei metadati. Verifica l’accesso effettivo nell’interfaccia di X; questo endpoint legge i metadati.
Sono inclusi i post delle community o le Community Notes?
Interroga i post delle community con X Community Posts. Le Community Notes sono annotazioni separate dei post. Questo endpoint restituisce i metadati delle community.
Posso usare questi conteggi per classificare l’attività delle community?
I totali di membri e moderatori descrivono le dimensioni. Per studiare l’attività, raccogli i post, scegli un periodo usando published_at nella tua applicazione e conta post, autori o interazioni all’interno di quel campione.
X API
Prova il flusso di lavoro con un URL pubblico di X
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di X