En el navegador, X sigue pareciendo una cronología. El contrato de datos públicos es más acotado: un nombre de usuario no es la URL de un post, una cita no es un retweet, una respuesta no es una cita, y un post eliminado o protegido debe fallar de forma limpia en lugar de convertirse en un registro vacío.
Este tutorial construye un flujo de producción con las API de X de SocQ. Abarca el acceso oficial frente al público, el enrutamiento de endpoints, la depuración de entradas, las tareas asíncronas, el significado de los campos, la frecuencia de actualización y el uso responsable.
Respuesta rápida: envíe nombres de usuario, URL de estados de
x.comotwitter.com, o una consulta de búsqueda aPOST /v1/x/{resource}, guarde el ID de tarea y consulte/v1/tasks/{id}. No junte citas, retweets y respuestas en una sola tabla sin una columna que distinga el recurso.
¿API oficial de X o una API de datos públicos?
La API oficial de X es de pago y funciona con permisos. Es el producto correcto cuando necesita publicar, enviar mensajes directos, administrar anuncios, seguir o dar Me gusta como usuario, o consumir streams y otras superficies autorizadas por cuenta. El acceso y los precios cambian; trate la documentación vigente para desarrolladores como la fuente de verdad para los productos de escritura y de socios.
SocQ es una capa de lectura pública para perfiles compatibles, posts conocidos, ventanas de posts de usuarios, búsqueda, relaciones de conversación y tendencias. No se autentica como un usuario de X ni reemplaza la publicación ni los anuncios oficiales. Para los precios y el planteamiento de proveedores, lea alternativas a la API de Twitter, API de scraping de Twitter y alternativas a TwitterAPI.io. Elija el modelo de acceso antes de elegir un endpoint.
Elegir el endpoint de X correcto
| Recurso | Endpoint | Entrada pública aceptada | Uso típico |
|---|---|---|---|
| Perfiles | /v1/x/profiles | Nombres de usuario, con o sin @ | Identidad pública y conteos visibles |
| Posts | /v1/x/posts | URL de estados de x.com o twitter.com | Un post conocido |
| Posts de un usuario | /v1/x/user-posts | Nombres de usuario | Posts públicos recientes de una cuenta |
| Búsqueda | /v1/x/search | Consulta | Descubrimiento de posts públicos por Latest o Top |
| Respuestas | /v1/x/post-replies | URL de estados | Respuestas a un post conocido |
| Citas | /v1/x/post-quotes | URL de estados | Citas de un post conocido |
También están disponibles:
post-retweeterspara URL de estados públicos.followers-listyfollowing-listpara nombres de usuario, conresults_limitde 200 a 2000 en pasos de 200.trendspara WOEID numéricos.
Las citas, los retweets y las respuestas son recursos distintos. Una cita tiene su propio texto de post. Una lista de retweeters es un conjunto de perfiles. Una respuesta es un post que pertenece a una conversación. No haga upsert de ellos como si fueran el mismo objeto.
Normalizar nombres de usuario, URL y consultas
Conserve el valor enviado y luego limpie una copia:
- Acepte nombres de usuario con o sin
@y luego guarde un único nombre de usuario canónico. - Acepte los hosts
x.comytwitter.com. Exija una ruta numérica/status/{id}para los endpoints que trabajan con posts. - Elimine los parámetros de consulta de seguimiento. No exija un host móvil o de idioma específico si el ID del estado está intacto.
- Elimine duplicados de los nombres de usuario sin distinguir mayúsculas de minúsculas y de los posts por ID de estado.
- Rechace las consultas y los nombres de usuario vacíos antes de enviarlos.
- Conserve las expresiones de búsqueda en la fila de origen para que los analistas puedan explicar por qué un post entró al conjunto de datos.
user-posts y search aceptan results_limit de 20 a 2000 en pasos de 20. El sort_by de la búsqueda es latest o top. post-replies también acepta sort_by con valor relevance, latest o likes.
Enviar una tarea de recopilación
Recopile perfiles:
curl -X POST "https://api.socq.ai/v1/x/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["openai","@github"]}'
Recopile posts conocidos desde cualquiera de los dos nombres de host:
curl -X POST "https://api.socq.ai/v1/x/posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"]}'
Recopile una ventana de posts de un usuario:
curl -X POST "https://api.socq.ai/v1/x/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["openai","github"],"results_limit":40}'
Busque posts públicos:
curl -X POST "https://api.socq.ai/v1/x/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"AI lang:en","results_limit":100,"sort_by":"latest"}'
Recopile las respuestas y las citas como tareas separadas:
curl -X POST "https://api.socq.ai/v1/x/post-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20,"sort_by":"latest"}'
curl -X POST "https://api.socq.ai/v1/x/post-quotes" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20}'
Guarde el ID de tarea devuelto junto con el nombre del recurso y las entradas canónicas.
Consultar la tarea sin crear duplicados
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Considere normales los estados queued y running. Use retroceso exponencial. Cuando la tarea termina con éxito, lea data.results.items y siga next_cursor mientras has_more sea true.
Un worker robusto debe conservar:
- El ID del lote y el ID de la tarea de SocQ.
- El recurso y los nombres de usuario, las URL o la consulta canónicos.
- Las horas de envío y de finalización.
- El estado terminal y la categoría del error.
- El último cursor de resultados procesado.
Que un worker se reinicie no es motivo para enviar de nuevo la misma búsqueda.
Los campos devueltos
Los registros comparten id, platform, resource, type, url, created_at, collected_at y extra.
Un perfil incluye username, name, description, avatar_url, cover_url, is_verified, is_private y métricas visibles. Las cuentas protegidas no son un objetivo de datos públicos.
Un post incluye text, language, author, métricas visibles, media, hashtags y mentions cuando son públicos. Use id como clave preferida de la entidad y la URL del estado como registro de origen.
Las respuestas y las citas reutilizan la estructura de post. Los retweeters reutilizan la estructura de perfil. Las tendencias son filas de descubrimiento acotadas a una ubicación, no posts.
Los posts eliminados y privados deben fallar en la entrada o en el límite de la tarea. No inserte un post en blanco, no invente ceros de interacción ni reutilice collected_at como created_at.
Los resultados de búsqueda son descubrimiento clasificado. latest y top son órdenes distintos de una ventana acotada, no un archivo histórico completo.
Worker en Python para perfiles, posts y búsqueda
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
def collect(resource, payload):
created = requests.post(
f"{BASE}/x/{resource}",
headers=HEADERS,
json=payload,
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
return task["results"]["items"]
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
profiles = collect("profiles", {"usernames": ["openai"]})
hits = collect("search", {
"query": "AI lang:en",
"results_limit": 40,
"sort_by": "latest",
})
Antes de llevar esto a producción, agregue paginación por cursor, reintentos acotados para los tiempos de espera agotados y las respuestas 5xx que admiten reintento, y upserts idempotentes.
Modelar por separado los posts y las instantáneas de métricas
La identidad de un post y sus métricas cambian a ritmos distintos.
x_entity
resource
platform_id
canonical_url_or_username
text_or_description
author_id
created_at
first_seen_at
last_seen_at
x_snapshot
resource
platform_id
collected_at
likes_count
replies_count
reposts_count
quotes_count
source_task_id
Haga upsert por resource + id. Guarde las citas, las respuestas y los posts de origen en la misma tabla de posts solo si resource sigue siendo una columna obligatoria. Mantenga los retweeters en una tabla de perfiles o de relaciones.
No calcule el crecimiento de las citas a partir de una instantánea de retweeters. Las métricas no son intercambiables.
Validar antes de guardar
platformdebe ser igual ax.resourcedebe coincidir con el endpoint.- Las URL de estados deben contener un ID numérico
/status/cuando el recurso trabaja con posts. - Los nombres de usuario de los autores deberían coincidir con la cuenta enviada cuando el recurso es
user-postsy el campo está presente. - Los conteos deben ser números no negativos o null.
- Las marcas de tiempo deben poder interpretarse.
- Una entrada privada o eliminada que falló no debe convertirse en un post vacío exitoso.
Conserve las filas no válidas en cuarentena junto con la carga útil sin procesar de la tarea.
Elegir un calendario de actualización por entidad
| Entidad | Frecuencia inicial razonable | Motivo |
|---|---|---|
| Perfil | Semanal o mensual | La biografía y los campos de identidad cambian lentamente |
| Post conocido | De cada hora a diaria mientras esté activo | Las métricas públicas se mueven rápido |
| Ventana de posts de un usuario | De cada hora a diaria para el monitoreo | Las cronologías están acotadas y clasificadas |
| Búsqueda | Según un calendario acorde con la consulta | latest y top no son archivos |
| Respuestas / citas | Cada hora mientras un post esté activo | Las relaciones de conversación llegan en ráfagas |
| Seguidores / seguidos | Semanal | Las listas son grandes y avanzan de 200 en 200 |
| Tendencias | Cada hora o algunas veces al día | Los conjuntos de WOEID rotan |
Reduzca la recopilación cuando la pregunta de negocio no necesite una instantánea más reciente.
Modos de falla comunes
La URL de un post no devuelve nada
Confirme que la URL sea pública, siga disponible y contenga /status/{id}. Los posts eliminados y protegidos deben fallar de forma limpia. Conserve el error a nivel de la entrada.
La búsqueda parece incompleta
results_limit fija el tope de la solicitud. La clasificación, la indexación y el cambio entre latest y top modifican la página. Guarde la consulta y el orden junto con los registros.
Las citas se guardaron como retweets
Son endpoints distintos y objetos distintos. Mantenga resource en la clave primaria.
Los trabajos de seguidores rechazan el límite
Seguidores y seguidos aceptan de 200 a 2000 en incrementos de 200. User-posts y search usan pasos de 20.
Las métricas no coinciden con las del navegador
Los conteos públicos son instantáneas. Pueden estar retrasados, redondeados u ocultos. Compare collected_at antes de culpar al parser.
El mismo usuario aparece dos veces
Canonice los nombres de usuario y prefiera un ID público estable. Mantenga una tabla de alias cuando una cuenta cambie de nombre.
Uso responsable de los datos de X
Recopile solo los campos públicos necesarios para un propósito legítimo. No eluda las cuentas protegidas, los bloqueos, los muros de inicio de sesión ni otros controles de acceso. Evite la creación de perfiles sensibles de personas y las decisiones automatizadas que puedan afectar de manera material a una persona sin salvaguardas.
Los datos de X pueden ser datos personales. Establezca una base legal cuando se requiera, defina reglas de retención y eliminación, proteja las claves de API y las exportaciones, y revise los términos vigentes de X con asesoría legal calificada. Una API de datos públicos no otorga una licencia para volver a publicar posts ni medios.
Scraping de X/Twitter: preguntas frecuentes (FAQ)
¿Es legal hacer scraping de X o Twitter?
No hay una respuesta universal. Depende de la jurisdicción, los datos, el método, el propósito, el contrato y las salvaguardas. Este tutorial no constituye asesoría legal.
¿Esto reemplaza la API oficial de X?
No. El acceso oficial sigue siendo necesario para publicar, mensajes directos, anuncios, streams y otras acciones con permisos. SocQ cubre las lecturas públicas compatibles.
¿Puedo recopilar posts privados o eliminados?
No. Esas entradas deben fallar de forma limpia. No eluda la protección.
¿Las citas son lo mismo que los retweets?
No. Las citas son posts. Los retweeters son perfiles. Las respuestas son un tercer recurso.
¿La búsqueda devuelve un historial completo?
No. Devuelve una ventana acotada y ordenada para una consulta.
¿Qué clave debo usar para eliminar duplicados?
Prefiera resource + id. Use como alternativa de respaldo una URL de estado o un nombre de usuario normalizados cuando falte el ID público.
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