Guide d'intégration

Concepts clés et bonnes pratiques pour intégrer les endpoints Timelines

Ce guide présente les concepts clés nécessaires pour intégrer les endpoints Timelines à votre application.

---

​

Authentification

​

Exigences relatives aux endpoints

Endpoint	App uniquement	Contexte utilisateur
Timeline des Publications de l’utilisateur	✓	✓
Timeline des mentions de l’utilisateur	✓	✓
Timeline d’accueil	—	✓ (obligatoire)

​

Métriques privées

Pour accéder aux métriques privées, vous devez vous authentifier au nom de l’auteur de la Publication :

Ces champs nécessitent une authentification avec contexte utilisateur :

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

---

​

Champs et expansions

Par défaut, les réponses incluent uniquement id, text et edit_history_tweet_ids. Pour demander des données supplémentaires :

​

Exemple de requête

cURL

shellscript

curl "https://api.x.com/2/users/123/tweets?\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Champs clés

Field	Description
created_at	Horodatage de création de la Publication
public_metrics	Nombre d’interactions
conversation_id	Identifiant de conversation
context_annotations	Catégories de sujets
entities	Hashtags, mentions, URL

Guide des champs et Expansions

En savoir plus sur la personnalisation des réponses

---

​

Pagination

Les timelines renvoient jusqu’à 100 Publications par requête. Utilisez la pagination pour des ensembles de résultats plus importants.

​

Fonctionnement

1. Effectuez une requête initiale avec max_results
2. Récupérez next_token à partir de l’objet meta
3. Incluez pagination_token dans la requête suivante
4. Répétez jusqu’à ce qu’aucun next_token ne soit renvoyé

​

Exemple

cURL

shellscript

# Première requête
curl "https://api.x.com/2/users/123/tweets?max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# Requête suivante avec un jeton de pagination
curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Guide de pagination

En savoir plus sur la pagination

---

​

Filtrer les résultats

​

Filtrage temporel

Paramètre	Description
start_time	Horodatage de la Publication la plus ancienne (ISO 8601)
end_time	Horodatage de la Publication la plus récente (ISO 8601)
since_id	Renvoie les Publications après cet identifiant
until_id	Renvoie les Publications avant cet identifiant

​

Paramètre exclude

Exclure certains types de publications des résultats :

cURL

shellscript

curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Valeur	Effet
retweets	Exclure les retweets
replies	Exclure les réponses

---

​

Limites de volume

Chaque timeline est soumise à des limites maximales de récupération :

Endpoint	Nombre maximal de Publications
Timeline des Publications de l’utilisateur	3 200 plus récentes
Publications de l’utilisateur (exclude=replies)	800 plus récentes
Timeline des mentions de l’utilisateur	800 plus récentes
Timeline d’accueil	3 200 ou 7 jours

Les requêtes de Publications au-delà de ces limites renvoient une réponse réussie, mais sans données.

---

​

Modifications des Publications

Les Publications peuvent être modifiées jusqu’à 5 fois dans un délai de 30 minutes. Les endpoints de timeline renvoient toujours la version la plus récente.

​

Considérations

• Les Publications de plus de 30 minutes sont considérées comme définitives
• Les cas d’utilisation en quasi temps réel doivent tenir compte des modifications potentielles
• Utilisez la fonctionnalité Post lookup pour vérifier l’état final si nécessaire

Principes de base de l’édition de Publications

En savoir plus sur l’édition de Publications

---

​

Métriques des Publications

​

Statistiques publiques

Disponibles pour toutes les Publications avec une authentification App-Only ou un contexte utilisateur :

{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12
  }
}

​

Métriques privées

Nécessite une authentification avec contexte d’utilisateur de la part de l’auteur de la Publication :

• Disponible uniquement pour les Publications des 30 derniers jours
• Renvoyées uniquement pour les Publications rédigées par l’utilisateur authentifié
• Renvoie une erreur pour les Publications d’autres utilisateurs

---

​

Cas particuliers

Métriques non publiques et pagination

Lorsque vous demandez des métriques non publiques pour des Publications âgées de plus de 30 jours, vous pouvez recevoir un next_token avec result_count: 0. Pour éviter cela :

• Limitez les requêtes aux 30 derniers jours
• Utilisez un max_results d’au moins 10

Métriques sponsorisées pour des Publications non sponsorisées

Demander des métriques sponsorisées pour des Publications qui n’ont pas été sponsorisées renvoie une réponse vide. Il s’agit d’un problème connu.

Texte de Retweet tronqué

Pour les Retweets dont le texte dépasse 140 caractères, le champ de texte est tronqué. Utilisez l’extension referenced_tweets.id pour récupérer le texte complet.

---

​

Prochaines étapes

Démarrage rapide du fil d’accueil

Récupérer le fil d’accueil d’un utilisateur

Démarrage rapide des mentions

Récupérer les mentions d’un utilisateur

Référence de l’API

Documentation complète de l’endpoint

Pagination

Gérer des ensembles de résultats volumineux