Pagination

Parcourir de grands ensembles de résultats

Lorsqu’une réponse d’API contient plus de résultats qu’il n’est possible d’en renvoyer en une seule fois, utilisez la pagination pour récupérer l’ensemble des pages de données.

---

​

Fonctionnement de la pagination

1. Effectuez votre requête initiale avec max_results
2. Vérifiez la présence d’un next_token dans l’objet meta de la réponse
3. S’il est présent, effectuez une autre requête en utilisant ce jeton comme valeur de pagination_token
4. Répétez jusqu’à ce qu’aucun next_token ne soit renvoyé

# Requête initiale
curl "https://api.x.com/2/users/12345/tweets?max_results=100" \
  -H "Authorization: Bearer $TOKEN"

# La réponse inclut next_token
# {"data": [...], "meta": {"next_token": "abc123", ...}}

# Page suivante
curl "https://api.x.com/2/users/12345/tweets?max_results=100&pagination_token=abc123" \
  -H "Authorization: Bearer $TOKEN"

---

​

Jetons de pagination

Jeton	Description
next_token	Dans le champ meta de la réponse. Utilisez-le pour obtenir la page suivante.
previous_token	Dans le champ meta de la réponse. Utilisez-le pour revenir à la page précédente.
pagination_token	Paramètre de la requête. Définissez-le sur la valeur de next_token ou previous_token.

---

​

Structure de la réponse

{
  "data": [
    {"id": "1234", "text": "..."},
    {"id": "1235", "text": "..."}
  ],
  "meta": {
    "result_count": 100,
    "next_token": "7140w9gefhslx3",
    "previous_token": "77qp89slxjd"
  }
}

Lorsqu’il n’y a plus de résultats, le paramètre next_token est omis :

{
  "data": [...],
  "meta": {
    "result_count": 42,
    "previous_token": "77qp89abc"
  }
}

---

​

Paramètres de pagination

Paramètre	Description	Valeur par défaut
max_results	Résultats par page	Spécifique à l’endpoint
pagination_token	Jeton issu de la réponse précédente	Aucune

Consultez la Référence de l’API de chaque endpoint pour connaître les limites spécifiques de max_results.

---

​

Exemple : parcourir tous les résultats avec la pagination

Python

import requests

def get_all_tweets(user_id, bearer_token):
    url = f"https://api.x.com/2/users/{user_id}/tweets"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {"max_results": 100}
    
    all_tweets = []
    
    while True:
        response = requests.get(url, headers=headers, params=params)
        data = response.json()
        
        if "data" in data:
            all_tweets.extend(data["data"])
        
        # Vérifier s'il existe une page suivante
        next_token = data.get("meta", {}).get("next_token")
        if not next_token:
            break
            
        params["pagination_token"] = next_token
    
    return all_tweets

JavaScript

async function getAllTweets(userId, bearerToken) {
  const url = `https://api.x.com/2/users/${userId}/tweets`;
  const headers = { Authorization: `Bearer ${bearerToken}` };
  
  let allTweets = [];
  let paginationToken = null;
  
  do {
    const params = new URLSearchParams({ max_results: 100 });
    if (paginationToken) {
      params.set("pagination_token", paginationToken);
    }
    
    const response = await fetch(`${url}?${params}`, { headers });
    const data = await response.json();
    
    if (data.data) {
      allTweets.push(...data.data);
    }
    
    paginationToken = data.meta?.next_token;
  } while (paginationToken);
  
  return allTweets;
}

---

​

Bonnes pratiques

Utilisez max_results

Demandez la valeur maximale possible pour max_results afin de réduire le nombre d’appels à l’API.

Gérez les pages partielles

La dernière page peut contenir moins de résultats que max_results.

Stockez les jetons

Enregistrez next_token si vous devez reprendre la pagination plus tard.

N'effectuez pas de polling avec la pagination

Pour obtenir de nouvelles données, utilisez since_id plutôt que de paginer en boucle.

---

​

Ordre des résultats

Les résultats sont renvoyés dans l’ordre chronologique inverse :

• Premier résultat de la première page = le plus récent
• Dernier résultat de la dernière page = le plus ancien

Cela s’applique sur chaque page et entre les pages.

---

​

Remarques

• Les jetons de pagination sont des chaînes opaques : ne cherchez pas à les analyser ni à les modifier
• Les jetons peuvent expirer après un certain temps
• Si vous obtenez moins de résultats que max_results, il peut encore rester des résultats (poursuivez jusqu’à ce qu’il n’y ait plus de next_token)
• Utilisez les SDK pour gérer automatiquement la pagination

---

​

Prochaines étapes

Limites de taux

Comprendre les limites de taux applicables à la pagination.

SDKs

Bibliothèques avec pagination intégrée.