Guide d'intégration

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

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Récupérer la timeline des Publications d'un utilisateur
for page in client.posts.get_user_posts(
    user_id="123",
    tweet_fields=["created_at", "public_metrics", "author_id"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"],
    max_results=100
):
    for post in page.data:
        print(f"{post.text} - {post.public_metrics}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Récupérer la timeline des Publications d'un utilisateur avec pagination
const paginator = client.posts.getUserPosts("123", {
  tweetFields: ["created_at", "public_metrics", "author_id"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.text} - ${JSON.stringify(post.public_metrics)}`);
  });
}

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

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

Exemple

cURL

# 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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Le SDK gère la pagination automatiquement
all_posts = []

for page in client.posts.get_user_posts(user_id="123", max_results=100):
    if page.data:
        all_posts.extend(page.data)

print(f"Nombre de publications trouvées : {len(all_posts)}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

async function getAllTimelinePosts(userId) {
  const allPosts = [];

  // Le SDK gère la pagination automatiquement avec l'itération asynchrone
  const paginator = client.posts.getUserPosts(userId, { maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allPosts.push(...page.data);
    }
  }

  return allPosts;
}

// Utilisation
const posts = await getAllTimelinePosts("123");
console.log(`Nombre de publications trouvées : ${posts.length}`);

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

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Exclure les retweets et les réponses
for page in client.posts.get_user_posts(
    user_id="123",
    exclude=["retweets", "replies"]
):
    for post in page.data:
        print(post.text)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Exclure les retweets et les réponses
const paginator = client.posts.getUserPosts("123", {
  exclude: ["retweets", "replies"],
});

for await (const page of paginator) {
  page.data?.forEach((post) => console.log(post.text));
}

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