# Données X

Récupérer des profils X, rechercher des utilisateurs et des publications, et paginer les timelines et les réponses.

Choisissez l'opération correspondant aux données dont vous avez besoin. Les cinq points de terminaison utilisent POST et renvoient le JSON à la racine, sans enveloppe commune `data`.

Tous les exemples utilisent `FELO_API_KEY` depuis l'[aperçu](https://openapi.felo.ai/fr/docs/data-api/guides/felo-overview.md). Les appels utilisent **le solde de plateforme**, et non les crédits Felo Pro. Les exemples de réponse sont illustratifs ; le contenu réel et les champs facultatifs varient.

## Choisissez une opération

| Besoin | Point de terminaison |
|---|---|
| Profils pour des noms d'utilisateur connus | `POST /api/v1/data/x/user/info` |
| Trouver des utilisateurs à partir d'une requête | `POST /api/v1/data/x/user/search` |
| Publications d'un utilisateur | `POST /api/v1/data/x/user/tweets` |
| Publications correspondant à une requête | `POST /api/v1/data/x/tweet/search` |
| Réponses à des publications connues | `POST /api/v1/data/x/tweet/replies` |

## 1. Obtenir des profils d'utilisateurs

`POST /api/v1/data/x/user/info`

| Champ | Type | Requis | Signification |
|---|---|---|---|
| `usernames` | tableau de strings | Oui | 1–100 noms d'utilisateur ; envoyez les identifiants sans `@` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'
```

La réponse contient `users` et `total`. Chaque utilisateur inclut `user_id`, `username` et `display_name` ; le texte du profil, les nombres d'abonnés, la vérification et d'autres métadonnées peuvent aussi être présents. Un lot peut renvoyer moins de profils que demandé. Faites la correspondance par nom d'utilisateur ou ID, pas par position dans le tableau.

```json
{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}
```

## 2. Rechercher des utilisateurs

`POST /api/v1/data/x/user/search`

| Champ | Type | Requis | Signification |
|---|---|---|---|
| `query` | string | Oui | 1–1 000 caractères |
| `cursor` | string | Non | Curseur de pagination, jusqu'à 4 000 caractères |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'
```

La réponse contient `users`, `total`, `has_next` et `next_cursor`. Cette opération n'a pas de paramètre `limit`.

```json
{"users":[],"total":0,"has_next":false,"next_cursor":null}
```

## 3. Obtenir la timeline d'un utilisateur

`POST /api/v1/data/x/user/tweets`

| Champ | Type | Requis | Signification |
|---|---|---|---|
| `username` | string | Un identifiant requis | Identifiant utilisateur, jusqu'à 100 caractères |
| `x_user_id` | string | Un identifiant requis | ID utilisateur, jusqu'à 100 caractères ; prioritaire sur `username` |
| `limit` | integer | Non | 1–1 000 ; l'implémentation actuelle utilise au moins 20, avec 20 par défaut |
| `cursor` | string | Non | Curseur de pagination, jusqu'à 4 000 caractères |
| `include_replies` | boolean | Non | Inclure les réponses imbriquées ; `false` par défaut |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'
```

La réponse contient `tweets`, `total`, `has_next` et `next_cursor`. Définir `limit` sous 20 ne garantit pas moins d'éléments renvoyés ni une facture plus faible. L'inclusion des réponses peut ajouter des données renvoyées et des résultats facturables.

### Limites de résultats et de réponses imbriquées

`limit` est le nombre cible de publications de premier niveau pour cette requête, pas un nombre de résultats garanti. L'implémentation actuelle utilise une cible d'au moins 20 : une cible de 20 lit une page amont ; des cibles plus élevées récupèrent automatiquement jusqu'à 50 pages. Avant chaque page, le temps écoulé est vérifié et l'on cesse de récupérer d'autres pages dès qu'il dépasse 60 secondes. Cette vérification ne garantit pas que l'ensemble de la requête HTTP se termine en 60 secondes.

La collecte s'arrête aussi lorsque la cible est atteinte, que l'amont n'a plus de page suivante, qu'une page est vide, ou que le curseur est manquant. Une réponse réussie peut donc contenir moins de publications que `limit`. Utilisez `has_next` et `next_cursor` pour continuer lorsque disponibles.

Avec `include_replies=true`, chaque publication renvoyée obtient jusqu'à 5 pages supplémentaires et au plus 100 réponses imbriquées. La collecte peut s'arrêter plus tôt en l'absence de page suivante, si une page est vide ou si le curseur ne peut pas avancer. Ces réponses imbriquées sont en dehors du `limit` et du `total` de premier niveau, mais peuvent ajouter des résultats facturables.

Les `replies` imbriquées ne constituent pas une archive complète des réponses et n'exposent pas de curseur de continuation séparé pour cette collecte supplémentaire. Pour paginer les réponses indépendamment, utilisez l'opération de lecture des réponses et le curseur qu'elle renvoie. Ne réutilisez pas le curseur de publication de premier niveau pour les réponses.

## 4. Rechercher des publications

`POST /api/v1/data/x/tweet/search`

| Champ | Type | Requis | Signification |
|---|---|---|---|
| `query` | string | Oui | Texte de recherche, 1–1 000 caractères |
| `query_type` | string | Non | `Latest` (par défaut) ou `Top` |
| `limit` | integer | Non | 1–1 000 ; l'implémentation actuelle utilise au moins 20, avec 20 par défaut |
| `cursor` | string | Non | Curseur de pagination, jusqu'à 4 000 caractères |
| `since_time` | integer or string | Non | Heure de début ; utilisez des secondes Unix pour une valeur numérique non ambiguë |
| `until_time` | integer or string | Non | Heure de fin ; utilisez des secondes Unix, pas des millisecondes |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'
```

La réponse contient `tweets`, `total`, `has_next` et `next_cursor`. Les objets publication incluent `id`, `content`, `author`, `created_at` et `metrics` ; les réponses et les publications citées/retweetées peuvent être imbriquées. Traitez les IDs comme des chaînes.

### Limites du nombre de résultats

`limit` est une cible, pas une garantie. L'implémentation actuelle utilise une cible d'au moins 20 : une cible de 20 lit une page amont ; des cibles plus élevées récupèrent automatiquement jusqu'à 50 pages. Le temps écoulé est vérifié avant chaque page, et aucune page supplémentaire n'est récupérée une fois qu'il dépasse 60 secondes. Une requête amont en cours peut encore prendre du temps ; il ne s'agit donc pas d'un délai global HTTP.

La collecte s'arrête aussi lorsque la cible est atteinte, que l'amont n'a plus de page suivante, qu'une page est vide, ou que le curseur est manquant. Renvoyer moins de publications que `limit` ne signifie pas que la requête a échoué ni que toutes les publications correspondantes ont été récupérées. Vérifiez `has_next` et `next_cursor` avant de continuer.

```json
{
  "tweets": [{
    "id":"example-post-id",
    "content":"Example post content",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}
```

## 5. Lire les réponses

`POST /api/v1/data/x/tweet/replies`

| Champ | Type | Requis | Signification |
|---|---|---|---|
| `tweet_ids` | string ou tableau de strings | Oui | Un ID de publication ou un lot allant jusqu'à 20 IDs |
| `cursor` | string | Non | Jusqu'à 4 000 caractères ; à utiliser avec un seul ID de publication |
| `since_time` | integer | Non | Heure de début en secondes Unix |
| `until_time` | integer | Non | Heure de fin en secondes Unix |

Remplacez l'espace réservé par un vrai ID de publication :

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'
```

Contrairement à la timeline et à la recherche de publications, les réponses sont regroupées sous `results`. Chaque entrée possède son propre état de pagination :

```json
{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}
```

### Limites de réponses par requête

Chaque requête lit une page de réponses amont par `tweet_id` et conserve au plus 100 réponses ; elle ne récupère pas automatiquement chaque page de réponses. Dans un lot allant jusqu'à 20 IDs, la limite de 100 réponses s'applique séparément à chaque entrée `results`. Les nombres réels peuvent être inférieurs.

Le `total` de chaque entrée est le nombre de réponses renvoyées dans cette entrée, pas le nombre complet de réponses de la publication. Pour continuer, utilisez le `next_cursor` de cette entrée et envoyez uniquement son ID de publication unique dans la requête suivante. Il n'existe pas de paramètre `limit` permettant d'augmenter le plafond par requête.

## Pagination et contrôle des coûts

`total` compte le tableau correspondant dans la réponse actuelle : les publications de premier niveau pour les requêtes de publication, ou les réponses dans chaque entrée de résultat pour les requêtes de réponses. Il ne s'agit pas d'un nombre global de correspondances, d'un nombre complet de réponses d'une publication, ni du total final facturable.

1. Envoyez la première requête sans `cursor`.
2. Lisez `has_next` et `next_cursor` dans la réponse. Pour les réponses, lisez-les dans chaque entrée de résultat.
3. Si une autre page existe et que le curseur n'est pas vide, renvoyez-le inchangé avec la même requête. Pour un lot de réponses, continuez chaque publication séparément.
4. Arrêtez-vous lorsqu'il n'y a pas de page suivante, lorsqu'un curseur se répète, ou lorsque votre propre limite de pages ou de dépenses est atteinte.

Les métadonnées de pagination reflètent la dernière réponse amont ; la collection renvoyée peut être tronquée par un plafond de résultats. Même `has_next=false` ne garantit pas que tout l'historique X ou toutes les réponses ont été récupérés. Affichez le nombre réellement renvoyé plutôt que d'étiqueter un ensemble de résultats borné comme étant toutes les données disponibles.

Chaque page réussie peut entraîner des frais. Ces cinq opérations sont facturées par résultats retournés, et non par frais fixes par requête. Les réponses imbriquées et autres enregistrements renvoyés peuvent affecter le nombre facturé ; n'estimez pas le coût uniquement à partir de la longueur du tableau de premier niveau. Consultez les [prix actuels](https://openapi.felo.ai/api/v1/data/prices) et l'utilisation dans la console. Les champs d'objet complets figurent dans le [schéma OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).