Referencia de la API: cada endpoint y parámetro

URL base

https://xcrap.cc/v1

Sin autenticación

No hay clave, ni token, ni cabecera que enviar. Los límites son por IP y por endpoint.

OpenAPI

La spec completa se sirve en JSON y YAML. Apunta ahí cualquier generador o framework de agentes.

Formatos de respuesta

JSON es el predeterminado. Se cambia con ?format= o una cabecera Accept. Los dos valen; si están ambos, gana el parámetro de consulta.

?format=	Accept	Content-Type
`json`	`application/json`	`application/json`
`markdown`	`text/markdown`	`text/markdown`
`yaml`	`application/yaml`	`application/yaml`
`csv`	`text/csv`	`text/csv`
`html`	`text/html`	`text/html`

x-markdown-tokens

Cada respuesta markdown incluye una estimación de lo que costará leerla, para que un agente decida si un hilo cabe en su contexto antes de descargar el cuerpo.

Límites de peticiones

Los límites son por endpoint y no un cupo global, porque una petición bulk puede costar cincuenta llamadas upstream y un post en caché no cuesta ninguna. Cada respuesta lleva x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset.

Presupuesto	Peticiones	Ventana	Se aplica a
`tweet`	45	1 min	/v1/tweet
`user`	45	1 min	/v1/user
`thread`	15	1 min	/v1/thread
`timeline`	15	1 min	/v1/user/tweets
`graph`	15	1 min	/v1/user/followers, /v1/user/following
`replies`	15	1 min	/v1/replies
`history`	4	5 min	/v1/user/history
`search`	10	15 min	/v1/search
`bulk`	6	5 min	/v1/bulk
`media`	20	1 min	/v1/media, /v1/media/download
`meta`	90	1 min	/v1/trends
`page`	240	1 min	Páginas del sitio

¿Necesitas más? El plan para empresas ofrece límites más altos y capacidad dedicada. Ver Empresas →

Errores

Los errores vuelven en el formato que se pidió, con un código estable legible por máquinas, un mensaje que describe qué falló y una pista sobre qué hacer.

Estado	code	Qué hacer
400	`bad_request`	Falta un parámetro o está mal formado. Compruébalo con esta página.
404	`not_found`	El post o la cuenta está eliminado, suspendido, es privado o nunca existió.
429	`rate_limited`	Presupuesto del endpoint agotado. Espera el tiempo de retry-after, o mira el plan para empresas si necesitas límites más altos.
451	`opted_out`	Esa cuenta pidió ser excluida de XCrap.
500	`internal_error`	Culpa nuestra. Ya está reportado. Inténtalo de nuevo en breve.
502	`upstream_failed`	Todas las fuentes se negaron. Suele ser breve; reintenta en un minuto.
504	`upstream_timeout`	Una fuente no respondió a tiempo. Reintenta en un minuto.
503	`search_unavailable`	La capacidad de búsqueda está agotada por ahora, o la búsqueda no está configurada. Espera a retry-after.

Pruébalo

Rellena los parámetros y envía. Va a la API de verdad — no hay clave que añadir, así que no hay nada entre este formulario y una respuesta real.

GET /v1/tweet 45 / 1m

Un post, completamente resuelto

Obtiene un solo post con su autor, todos los contadores de interacción, los medios adjuntos en cada bitrate, los resultados de encuestas y el post citado, desplegado un nivel.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`url` Obligatorio	`string`	ninguno	La URL del post o su id numérico. x.com, twitter.com, los espejos fx/vx y un id suelto funcionan.
`download`	`boolean`	ninguno	Envía Content-Disposition para que el navegador guarde la respuesta como archivo.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/tweet?url=https://x.com/jack/status/20&format=markdown

Pruébalo

url Obligatorio

download

format

fresh

GET /v1/tweet

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/thread 15 / 1m

Un hilo completo, desplegado en orden

Dale cualquier post de un hilo, incluido el primero, y devuelve los posts del autor en orden de lectura. X solo expone el padre de un post, así que XCrap recompone la cronología del autor por id de conversación para recorrer el hilo hacia delante.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`url` Obligatorio	`string`	ninguno	Cualquier post del hilo.
`max_tweets`	`integer`	`25`	Hasta dónde llegar, de 1 a 100. La respuesta indica si se truncó.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/thread?url=https://x.com/naval/status/1002103360646823936&format=markdown

Pruébalo

url Obligatorio max_tweets

format

fresh

GET /v1/thread

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/replies 15 / 1m

Las respuestas a un post

Una página de respuestas a un post, las más gustadas o las más recientes primero, con el propio post incluido. Solo vuelven las respuestas directas: una respuesta a una respuesta pertenece a su propia conversación. No hay paginación: es la única página que X sirve para el post, hasta unas cien respuestas.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`url` Obligatorio	`string`	ninguno	El post cuyas respuestas leer: su URL o id numérico.
`sort`	`string`	`top`	top para las más gustadas primero, recent para las más recientes primero.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/replies?url=https://x.com/naval/status/1002103360646823936&sort=top&format=markdown

Pruébalo

url Obligatorio

sort

format

fresh

GET /v1/replies

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/search 10 / 15m

Buscar posts

Búsqueda de texto completo en X, con los operadores que entiende la búsqueda de X: from:, to:, "frase exacta", -excluir, lang:, filter:links y el resto. Elige los posts más recientes o los más destacados, o solo los que tienen fotos o vídeos. Una página por llamada; pasa next_cursor para la siguiente. La búsqueda tiene el presupuesto más ajustado de todos los endpoints y sus resultados se guardan en caché diez minutos.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`q` Obligatorio	`string`	ninguno	Qué buscar, incluidos los operadores de búsqueda de X.
`feed`	`string`	`latest`	latest, top, photos o videos.
`since`	`string`	ninguno	Post más antiguo que debe coincidir, como una fecha tal que 2025-01-01 o una marca de tiempo ISO completa.
`until`	`string`	ninguno	Post más reciente que debe coincidir, como fecha o marca de tiempo ISO completa.
`cursor`	`string`	ninguno	El next_cursor de una respuesta anterior.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/search?q=from:nasa%20mars&feed=latest&format=markdown

Pruébalo

q Obligatorio

feed

since until cursor

format

fresh

GET /v1/search

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/user 45 / 1m

Un perfil

Biografía, ubicación, sitio web, fecha de alta, tipo de verificación, avatar y banner a resolución completa, y los recuentos de seguidores, seguidos, posts y medios.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`handle` Obligatorio	`string`	ninguno	El handle, con o sin @, o una URL de perfil completa.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/user?handle=naval&format=markdown

Pruébalo

handle Obligatorio

format

fresh

GET /v1/user

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/user/tweets 15 / 1m

Los posts de una cuenta

Una página de los posts de una cuenta, de más reciente a más antiguo. La paginación es por cursor y no por offset, porque una cronología se mueve mientras la lees y un offset saltaría o repetiría posts sin avisar.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`handle` Obligatorio	`string`	ninguno	La cuenta a leer.
`count`	`integer`	`20`	Cuántos posts devolver, de 1 a 100.
`cursor`	`string`	ninguno	El next_cursor de una respuesta anterior.
`exclude_replies`	`boolean`	`true`	Excluye las respuestas de la cuenta a otras personas.
`media_only`	`boolean`	`false`	Solo posts con imagen o vídeo.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/user/tweets?handle=naval&count=20

Pruébalo

handle Obligatorio count cursor

exclude_replies

media_only

format

fresh

GET /v1/user/tweets

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/user/followers 15 / 1m

Quién sigue a una cuenta

Una página de las cuentas que siguen a esta, cada una como perfil completo. X decide el tamaño de página, normalmente unas decenas; pasa next_cursor para la siguiente página, y es null en la última.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`handle` Obligatorio	`string`	ninguno	La cuenta cuyos seguidores listar.
`cursor`	`string`	ninguno	El next_cursor de una respuesta anterior.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/user/followers?handle=jack&format=markdown

Pruébalo

handle Obligatorio cursor

format

fresh

GET /v1/user/followers

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/user/following 15 / 1m

A quién sigue una cuenta

Una página de las cuentas que sigue esta, cada una como perfil completo. X decide el tamaño de página; pasa next_cursor para la siguiente página, y es null en la última.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`handle` Obligatorio	`string`	ninguno	La cuenta cuyos seguidos listar.
`cursor`	`string`	ninguno	El next_cursor de una respuesta anterior.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/user/following?handle=jack&format=markdown

Pruébalo

handle Obligatorio cursor

format

fresh

GET /v1/user/following

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/user/history 4 / 5m

Los posts de una cuenta, en bloque

Recorre la cronología de una cuenta y devuelve hasta 1.000 posts en una respuesta, de más reciente a más antiguo, opcionalmente dentro de un rango de fechas. El recorrido tarda aproximadamente un segundo por cada veinte posts, así que para una exportación grande pide format=ndjson: los posts llegan uno por línea a medida que se obtienen, más o menos de más reciente a más antiguo, en lugar de todos al final. Cuanto más atrás esté el rango, más incompleta es la cronología de X, y un rango de hace años puede volver escaso o vacío.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`handle` Obligatorio	`string`	ninguno	La cuenta a exportar.
`max_posts`	`integer`	`200`	Se detiene tras este número de posts, de 1 a 1000.
`since`	`string`	ninguno	Post más antiguo a incluir, como una fecha tal que 2025-01-01 o una marca de tiempo ISO completa.
`until`	`string`	ninguno	Post más reciente a incluir, como fecha o marca de tiempo ISO completa.
`include_replies`	`boolean`	`false`	Incluye las respuestas de la cuenta a otras personas.
`include_reposts`	`boolean`	`false`	Incluir los posts que la cuenta reposteó de otras cuentas.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html, o ndjson para transmitir un post por línea. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/user/history?handle=naval&max_posts=200&since=2025-01-01

Pruébalo

handle Obligatorio max_posts since until

include_replies

include_reposts

format

fresh

GET /v1/user/history

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/trends 90 / 1m

Lo que es tendencia

Los temas en tendencia ahora mismo con la etiqueta de contexto que X añade a cada uno. En caché cinco minutos en lugar de cinco días, porque una lista de tendencias caducada es peor que ninguna.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`count`	`integer`	`20`	Cuántos temas, de 1 a 50.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/trends?count=10&format=markdown

Pruébalo

count

format

fresh

GET /v1/trends

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/media 20 / 1m

Listar los medios de un post

Cada archivo adjunto a un post: tipo, dimensiones, duración, el texto alternativo del autor, cada versión de vídeo que codificó X y un enlace de descarga listo para cada uno.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`url` Obligatorio	`string`	ninguno	El post a inspeccionar.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

https://xcrap.cc/v1/media?url=https://x.com/i/status/1671370010743263233

Pruébalo

url Obligatorio

format

fresh

GET /v1/media

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

GET /v1/media/download 20 / 1m

Descargar un archivo

Transmite el archivo directamente con una cabecera Content-Disposition. Nada se almacena en búfer ni se escribe en nuestro disco, que es lo que significa en la práctica la promesa de retención de la política de privacidad.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`url` Obligatorio	`string`	ninguno	El post al que pertenece el archivo.
`index`	`integer`	`0`	Qué archivo, cuando un post tiene varios.
`quality`	`string`	`best`	best o worst. Solo vídeo; las imágenes tienen una sola resolución.

Ejemplo

https://xcrap.cc/v1/media/download?url=https://x.com/i/status/1671370010743263233&index=0

Pruébalo

url Obligatorio index

quality

GET /v1/media/download

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.

POST /v1/bulk 6 / 5m

Hasta cincuenta posts de una vez

Resuelve muchos posts en una petición. Los fallos son por elemento: un enlace roto devuelve un error para esa entrada y todas las demás vuelven igualmente. GET también funciona, con parámetros url repetidos o separados por comas.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`urls` Obligatorio	`string[]`	ninguno	De una a cincuenta URL o ids de posts, en el cuerpo JSON.
`format`	`string`	`json`	Formato de respuesta: json, markdown, yaml, csv o html. Tiene prioridad sobre la cabecera Accept.
`fresh`	`boolean`	`false`	Omite la caché y vuelve a obtener los datos de origen. Úsalo con moderación.

Ejemplo

curl -X POST https://xcrap.cc/v1/bulk \
  -H 'content-type: application/json' \
  -d '{"urls":["https://x.com/jack/status/20","1671370010743263233"]}'

Pruébalo

body application/json

format

fresh

POST /v1/bulk

Los límites de uso se aplican aquí exactamente igual que en cualquier otro sitio.