XAPI de comunidades de TwitterAPI de información de comunidades de XAPI de detalles de comunidades de TwitterMetadatos de comunidades

Cómo obtener los detalles de una comunidad de Twitter/X con una API

Arme una tabla de perfiles de comunidades de Twitter/X con SocQ. Exporte nombres, reglas y conteos con enlaces de origen y fechas de captura, y luego conecte las publicaciones para su investigación.

SocQActualizado el 16 de octubre de 20267 min de lectura

Use SocQ para organizar en una tabla de perfiles los nombres, las descripciones, las reglas y los conteos de miembros y moderadores de las comunidades de Twitter/X. Guarde las fuentes y las fechas de captura, y luego conecte las publicaciones con el contexto registrado de la comunidad para su revisión.

La API X Community de SocQ consulta los metadatos a partir de la URL pública de una comunidad. Esta guía cubre las solicitudes, los campos devueltos y las exportaciones en JSON y CSV con enlaces de origen y fechas de recolección.

Respuesta rápida: Coloque los enlaces x.com/i/communities/{numeric_id} en urls y envíelos a POST /v1/x/community. Cuando la tarea termine con éxito, lea los nombres, las descripciones, las reglas, los conteos de miembros y moderadores, y las políticas de ingreso e invitación en data.results.items. Consulte las publicaciones por separado con Community Posts.

Arme una tabla de perfiles a partir de las URL de las comunidades

Coloque la URL de una comunidad en urls para consultar su nombre, su descripción, sus reglas, los conteos de miembros y moderadores, y sus políticas de ingreso e invitación. Este ejemplo usa la comunidad Build in Public:

https://x.com/i/communities/1493446837214187523

El último segmento numérico es el ID de la comunidad. Indique en urls la URL completa /i/communities/{numeric_id}.

Si parte de un nombre, primero busque la URL de la comunidad. Relacione los registros por el ID numérico de la comunidad y mantenga separadas las comunidades con distinto ID aunque sus nombres coincidan.

PreguntaUse
¿Qué metadatos hay disponibles para esta comunidad?X Community
¿Qué publicaciones se pueden recolectar de la comunidad?X Community Posts
¿Cómo se relacionan las publicaciones de una misma conversación?X Thread Context

Este endpoint consulta los metadatos de las comunidades temáticas. Las Community Notes son anotaciones asociadas a las publicaciones y constituyen un tipo de dato distinto.

Solicite los detalles de la comunidad

Defina SOCQ_API_KEY y luego envíe la 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"]}'

Para un lote, agregue más enlaces de comunidades públicas a urls. Cada registro devuelto describe una comunidad; cuente los resultados a partir de los registros que realmente se devolvieron.

Guarde data.task_id como TASK_ID y luego consulte la tarea existente:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Espere entre consultas mientras el estado sea queued, running o retrying. Cuando llegue a succeeded, lea data.results.items y las demás páginas de resultados almacenadas. Si la tarea falla, revise data.error_message. La paginación de la tarea lee datos guardados; no actualiza la información de la comunidad.

Lea las reglas, los conteos y las políticas de ingreso

Este ejemplo de metadatos muestra algunos campos seleccionados y una regla de la lista de reglas:

{
  "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 almacena la descripción, rules la lista estructurada de reglas y metrics los conteos. Mantenga separados los nombres y las descripciones de las reglas, y use null cuando la fuente omita la descripción.

metrics.members_count registra el total de miembros y metrics.moderators_count el total de moderadores. Guarde sus fechas de recolección para comparar los conteos de una misma comunidad entre capturas.

join_policy e invites_policy almacenan las cadenas originales de las políticas de ingreso e invitación. Conserve el valor original al etiquetar un valor conocido y muestre tal como se devuelven los valores desconocidos. Verifique el acceso real en la interfaz actual del producto de X.

Exporte una tabla de perfiles de comunidades con Python

Guarde este asistente de tareas, que usa solo la biblioteca estándar, como 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")

Guarde el exportador como export_communities.py en el mismo directorio:

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

El JSON conserva los registros estándar sin procesar y los enlaces enviados. El CSV ofrece una fila de revisión por cada comunidad devuelta, con las reglas serializadas como JSON para que las comas y los saltos de línea no destruyan su estructura. rules_json=null se distingue de una lista vacía. El texto público con aspecto de fórmula se escapa solo en el CSV, y los identificadores deben importarse como texto.

Cuando una entrada no devuelva metadatos, registre por separado el resultado vacío y la fecha de la consulta. Conserve los metadatos guardados anteriormente con su fecha de recolección original para las comparaciones históricas.

Conecte los metadatos de la comunidad con las publicaciones recolectadas

Use la misma URL de comunidad confirmada con X Community Posts cuando necesite las conversaciones. Esto inicia una tarea distinta, con su propio límite de resultados. El tutorial de publicaciones de comunidades muestra cómo conservar la comunidad de origen de la entrada al exportar las publicaciones.

Guarde el ID de la comunidad, la URL de origen, el ID de la tarea y la fecha de recolección junto con los metadatos. Asocie la comunidad de entrada a cada publicación recolectada para poder unir las tablas de perfiles y de publicaciones por el ID de la comunidad.

Revise juntas la descripción, las reglas y las publicaciones recolectadas, con sus respectivas fechas de captura. Para las relaciones de respuesta de una publicación, continúe con el tutorial de contexto de hilos.

Convierta los metadatos de comunidades en un recurso de investigación reutilizable

SocQ organiza los metadatos de las comunidades en campos estándar. Use el código para guardar una tabla de perfiles y las reglas estructuradas, y luego una las publicaciones recolectadas por el ID de la comunidad. Las descripciones, las reglas y las conversaciones comparten una fuente explícita para los archivos de investigación, las revisiones de muestras y las actualizaciones con fecha.

Abra X Community y consulte su URL de origen.

Preguntas frecuentes (FAQ)

¿Qué devuelve la API de comunidades de Twitter?

Nombres, descripciones, reglas, conteos de miembros y moderadores, políticas de ingreso y políticas de invitación de las comunidades. Consulte la página de la API X Community para ver las definiciones de los campos y la facturación.

¿Cómo se consultan los metadatos después del anuncio de migración de las comunidades?

X publicó un anuncio de migración de Communities a XChat. Use la URL de la comunidad de destino para consultar los metadatos: lea los registros devueltos cuando la tarea termine con éxito, guarde la fecha de consulta en los resultados vacíos y revise los detalles del error si falla. Verifique las funciones de ingreso y participación en la interfaz actual de X.

¿Se puede buscar una comunidad por su nombre?

La consulta recibe URL de comunidades. Confirme el enlace asociado al nombre y luego envíelo en urls.

¿El conteo de miembros incluye una lista de miembros o moderadores?

La respuesta contiene conteos agregados de miembros y moderadores. Los directorios de cuentas individuales son datos distintos y no forman parte de esta respuesta de metadatos.

¿Una política Open significa que puedo ingresar ahora?

Open es el valor de la política de ingreso que se devuelve en los metadatos. Verifique el acceso actual en la interfaz de X; este endpoint lee los metadatos.

¿Se incluyen las publicaciones de la comunidad o las Community Notes?

Consulte las publicaciones de la comunidad con X Community Posts. Las Community Notes son anotaciones de publicaciones independientes. Este endpoint devuelve los metadatos de la comunidad.

¿Puedo usar estos conteos para clasificar la actividad de las comunidades?

Los totales de miembros y moderadores describen el tamaño. Para estudiar la actividad, recolecte publicaciones, seleccione un periodo con published_at en su aplicación y cuente las publicaciones, los autores o las interacciones dentro de esa muestra.

X API

Probar el flujo de trabajo con una URL pública de X

Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.

Ver las API de X