Référence API : chaque endpoint et paramètre

URL de base

https://xcrap.cc/v1

Aucune authentification

Aucune clé, aucun jeton, aucun en-tête à envoyer. Les limites de débit sont par IP et par endpoint.

OpenAPI

La spec complète est servie en JSON et YAML. Pointez n'importe quel générateur ou framework d'agents dessus.

Formats de réponse

JSON par défaut. Changez avec ?format= ou un en-tête Accept. Les deux s'accordent ; le paramètre de requête l'emporte quand les deux sont présents.

?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

Chaque réponse markdown porte une estimation de son coût de lecture, pour qu'un agent puisse décider si un fil tient dans son contexte avant d'en récupérer le corps.

Limites de débit

Les limites sont par endpoint plutôt qu'un budget global unique, parce qu'une requête bulk peut coûter cinquante appels en amont et un post en cache n'en coûte aucun. Chaque réponse porte x-ratelimit-limit, x-ratelimit-remaining et x-ratelimit-reset.

Budget	Requêtes	Fenêtre	S'applique à
`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	Pages du site

Besoin de plus ? L'offre Entreprise propose des limites plus hautes et une capacité dédiée. Voir l'offre Entreprise →

Erreurs

Les erreurs reviennent dans le format demandé, avec un code stable lisible par machine, un message décrivant ce qui a échoué et un indice sur la marche à suivre.

Statut	code	Que faire
400	`bad_request`	Un paramètre est manquant ou mal formé. Vérifiez-le par rapport à cette page.
404	`not_found`	Le post ou le compte est supprimé, suspendu, privé ou n'a jamais existé.
429	`rate_limited`	Budget de l'endpoint épuisé. Attendez la durée indiquée dans retry-after, ou voyez l'offre Entreprise pour des limites plus hautes.
451	`opted_out`	Ce compte a demandé à être exclu de XCrap.
500	`internal_error`	Notre faute. Déjà signalé. Réessayez sous peu.
502	`upstream_failed`	Toutes les sources ont refusé. C'est généralement bref ; réessayez dans une minute.
504	`upstream_timeout`	Une source n'a pas répondu à temps. Réessayez dans une minute.
503	`search_unavailable`	La capacité de recherche est épuisée pour l'instant, ou la recherche n'est pas configurée. Attendez retry-after.

Essayer

Remplissez les paramètres et envoyez. Ça part vers la vraie API — il n'y a pas de clé à ajouter, donc rien ne s'interpose entre ce formulaire et une réponse réelle.

GET /v1/tweet 45 / 1m

Un post, entièrement résolu

Récupère un seul post avec son auteur, tous les compteurs d'engagement, les médias joints à chaque débit, les résultats de sondage et le post cité, déplié sur un niveau.

Paramètres

Paramètre	Type	Par défaut	Description
`url` Requis	`string`	aucune	L'URL du post ou son identifiant numérique. x.com, twitter.com, les miroirs fx/vx et un identifiant seul fonctionnent tous.
`download`	`boolean`	aucune	Envoie Content-Disposition pour que le navigateur enregistre la réponse comme un fichier.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

url Requis

download

format

fresh

GET /v1/tweet

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/thread 15 / 1m

Un fil entier, déroulé dans l'ordre

Donnez-lui n'importe quel post d'un fil, y compris le premier, et il renvoie les posts de l'auteur dans l'ordre de lecture. X n'expose que le parent d'un post, alors XCrap recoud la timeline de l'auteur par identifiant de conversation pour parcourir le fil vers l'avant.

Paramètres

Paramètre	Type	Par défaut	Description
`url` Requis	`string`	aucune	N'importe quel post du fil.
`max_tweets`	`integer`	`25`	Profondeur, de 1 à 100. La réponse indique si elle a été tronquée.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

url Requis max_tweets

format

fresh

GET /v1/thread

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/replies 15 / 1m

Les réponses sous un post

Une page de réponses à un post, les plus aimées ou les plus récentes d'abord, avec le post lui-même. Seules les réponses directes sont renvoyées : une réponse à une réponse appartient à sa propre conversation. Pas de pagination : c'est l'unique page que X sert pour ce post, jusqu'à une centaine de réponses.

Paramètres

Paramètre	Type	Par défaut	Description
`url` Requis	`string`	aucune	Le post dont lire les réponses : son URL ou son identifiant numérique.
`sort`	`string`	`top`	top pour les plus aimées d'abord, recent pour les plus récentes d'abord.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

url Requis

sort

format

fresh

GET /v1/replies

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/search 10 / 15m

Rechercher des posts

Recherche plein texte sur X, avec les opérateurs que la recherche de X comprend : from:, to:, "expression exacte", -exclusion, lang:, filter:links et les autres. Choisissez les posts les plus récents ou les plus populaires, ou seulement ceux avec photos ou vidéos. Une page par appel ; passez next_cursor pour la suivante. La recherche a le budget le plus serré de tous les endpoints, et ses résultats sont mis en cache dix minutes.

Paramètres

Paramètre	Type	Par défaut	Description
`q` Requis	`string`	aucune	Ce qu'il faut chercher, opérateurs de recherche X compris.
`feed`	`string`	`latest`	latest, top, photos ou videos.
`since`	`string`	aucune	Post le plus ancien à retenir, sous forme de date comme 2025-01-01 ou d'horodatage ISO complet.
`until`	`string`	aucune	Post le plus récent à retenir, sous forme de date ou d'horodatage ISO complet.
`cursor`	`string`	aucune	Le next_cursor d'une réponse précédente.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

q Requis

feed

since until cursor

format

fresh

GET /v1/search

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/user 45 / 1m

Un profil

Bio, localisation, site web, date d'inscription, type de vérification, avatar et bannière en pleine résolution, ainsi que les nombres d'abonnés, d'abonnements, de posts et de médias.

Paramètres

Paramètre	Type	Par défaut	Description
`handle` Requis	`string`	aucune	Le handle, avec ou sans @, ou une URL de profil complète.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

handle Requis

format

fresh

GET /v1/user

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/user/tweets 15 / 1m

Les posts d'un compte

Une page des posts d'un compte, du plus récent au plus ancien. La pagination se fait par curseur plutôt que par offset, car une timeline bouge pendant qu'on la lit et un offset sauterait ou répéterait des posts sans prévenir.

Paramètres

Paramètre	Type	Par défaut	Description
`handle` Requis	`string`	aucune	Le compte à lire.
`count`	`integer`	`20`	Nombre de posts à renvoyer, de 1 à 100.
`cursor`	`string`	aucune	Le next_cursor d'une réponse précédente.
`exclude_replies`	`boolean`	`true`	Exclut les réponses du compte à d'autres personnes.
`media_only`	`boolean`	`false`	Uniquement les posts avec une image ou une vidéo.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

handle Requis count cursor

exclude_replies

media_only

format

fresh

GET /v1/user/tweets

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/user/followers 15 / 1m

Qui suit un compte

Une page des comptes qui suivent celui-ci, chacun sous forme de profil complet. X décide de la taille de page, généralement quelques dizaines ; passez next_cursor pour la page suivante, il vaut null sur la dernière.

Paramètres

Paramètre	Type	Par défaut	Description
`handle` Requis	`string`	aucune	Le compte dont lister les abonnés.
`cursor`	`string`	aucune	Le next_cursor d'une réponse précédente.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

handle Requis cursor

format

fresh

GET /v1/user/followers

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/user/following 15 / 1m

Qui un compte suit

Une page des comptes que celui-ci suit, chacun sous forme de profil complet. X décide de la taille de page ; passez next_cursor pour la page suivante, il vaut null sur la dernière.

Paramètres

Paramètre	Type	Par défaut	Description
`handle` Requis	`string`	aucune	Le compte dont lister les abonnements.
`cursor`	`string`	aucune	Le next_cursor d'une réponse précédente.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

handle Requis cursor

format

fresh

GET /v1/user/following

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/user/history 4 / 5m

Les posts d'un compte, en masse

Parcourt la timeline d'un compte et renvoie jusqu'à 1 000 posts en une réponse, du plus récent au plus ancien, éventuellement dans une fenêtre de dates. Le parcours prend environ une seconde par vingt posts ; pour un gros export, demandez format=ndjson : les posts arrivent alors un par ligne au fil de la récupération, à peu près du plus récent au plus ancien, au lieu d'arriver tous à la fin. Plus une fenêtre est ancienne, plus la timeline de X est lacunaire, et une fenêtre vieille de plusieurs années peut revenir maigre ou vide.

Paramètres

Paramètre	Type	Par défaut	Description
`handle` Requis	`string`	aucune	Le compte à exporter.
`max_posts`	`integer`	`200`	S'arrête après ce nombre de posts, de 1 à 1000.
`since`	`string`	aucune	Post le plus ancien à inclure, sous forme de date comme 2025-01-01 ou d'horodatage ISO complet.
`until`	`string`	aucune	Post le plus récent à inclure, sous forme de date ou d'horodatage ISO complet.
`include_replies`	`boolean`	`false`	Inclut les réponses du compte à d'autres personnes.
`include_reposts`	`boolean`	`false`	Inclure les posts que le compte a repostés depuis d’autres comptes.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html, ou ndjson pour diffuser un post par ligne. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

handle Requis max_posts since until

include_replies

include_reposts

format

fresh

GET /v1/user/history

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/trends 90 / 1m

Ce qui est tendance

Les sujets tendance du moment avec l'étiquette de contexte que X attache à chacun. Mis en cache cinq minutes plutôt que cinq jours, car une liste de tendances périmée est pire que rien.

Paramètres

Paramètre	Type	Par défaut	Description
`count`	`integer`	`20`	Nombre de sujets, de 1 à 50.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

count

format

fresh

GET /v1/trends

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/media 20 / 1m

Lister les médias d'un post

Chaque fichier joint à un post : type, dimensions, durée, texte alternatif de l'auteur, chaque rendu vidéo encodé par X, et un lien de téléchargement prêt à l'emploi pour chacun.

Paramètres

Paramètre	Type	Par défaut	Description
`url` Requis	`string`	aucune	Le post à inspecter.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

url Requis

format

fresh

GET /v1/media

Les limites de débit s'appliquent ici exactement comme ailleurs.

GET /v1/media/download 20 / 1m

Télécharger un fichier

Transmet le fichier directement avec un en-tête Content-Disposition. Rien n'est mis en mémoire tampon ni écrit sur notre disque, ce qui est ce que la promesse de conservation de la politique de confidentialité signifie en pratique.

Paramètres

Paramètre	Type	Par défaut	Description
`url` Requis	`string`	aucune	Le post auquel le fichier appartient.
`index`	`integer`	`0`	Quel fichier, quand un post en contient plusieurs.
`quality`	`string`	`best`	best ou worst. Vidéo uniquement ; les images n'ont qu'une résolution.

Exemple

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

Essayer

url Requis index

quality

GET /v1/media/download

Les limites de débit s'appliquent ici exactement comme ailleurs.

POST /v1/bulk 6 / 5m

Jusqu'à cinquante posts d'un coup

Résout de nombreux posts en une requête. Les échecs sont par élément : un lien mort renvoie une erreur pour cette entrée et toutes les autres reviennent quand même. GET fonctionne aussi, avec des paramètres url répétés ou séparés par des virgules.

Paramètres

Paramètre	Type	Par défaut	Description
`urls` Requis	`string[]`	aucune	Une à cinquante URL ou identifiants de posts, dans le corps JSON.
`format`	`string`	`json`	Format de réponse : json, markdown, yaml, csv ou html. Prime sur l'en-tête Accept.
`fresh`	`boolean`	`false`	Ignore le cache et récupère à nouveau à la source. À utiliser avec modération.

Exemple

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

Essayer

body application/json

format

fresh

POST /v1/bulk

Les limites de débit s'appliquent ici exactement comme ailleurs.