Paginación

Recorre conjuntos de resultados grandes

Cuando una respuesta de la API contiene más resultados de los que se pueden devolver en una sola respuesta, usa la paginación para recuperar todas las páginas de datos.

---

​

Cómo funciona la paginación

1. Realiza tu solicitud inicial con max_results
2. Comprueba si la respuesta incluye un next_token dentro del objeto meta
3. Si está presente, realiza otra solicitud usando ese token como pagination_token
4. Repite hasta que no se devuelva ningún next_token

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

# La respuesta incluye next_token
# {"data": [...], "meta": {"next_token": "abc123", ...}}

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

---

​

Tokens de paginación

Token	Descripción
next_token	En meta de la respuesta. Úsalo para obtener la siguiente página.
previous_token	En meta de la respuesta. Úsalo para volver a la página anterior.
pagination_token	Parámetro de la solicitud. Configúralo con el valor de next_token o previous_token.

---

​

Estructura de la respuesta

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

Cuando ya no hay más resultados, se omite next_token:

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

---

​

Parámetros de paginación

Parámetro	Descripción	Valor predeterminado
max_results	Resultados por página	Específico del endpoint
pagination_token	Token de la respuesta anterior	Ninguno

Consulta la Referencia de la API de cada endpoint para conocer los límites específicos de max_results.

---

​

Ejemplo: paginación de todos los resultados

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"])
        
        # Comprobar si hay una página siguiente
        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;
}

---

​

Mejores prácticas

Usa el máximo de resultados

Solicita el valor máximo permitido de max_results para minimizar las llamadas a la API.

Gestiona páginas incompletas

La última página puede tener menos resultados que max_results.

Almacena tokens

Guarda next_token si necesitas reanudar la paginación más tarde.

No hagas sondeos con paginación

Para datos nuevos, usa since_id en lugar de paginar repetidamente.

---

​

Orden de resultados

Los resultados se devuelven en orden cronológico inverso:

• Primer resultado en la primera página = más reciente
• Último resultado en la última página = más antiguo

Esto se aplica tanto dentro de cada página como entre páginas.

---

​

Notas

• Los tokens de paginación son cadenas opacas: no los analices ni los modifiques
• Los tokens pueden expirar después de cierto tiempo
• Si obtienes menos resultados que max_results, es posible que aún existan más (continúa hasta que ya no haya next_token)
• Usa los SDKs para la gestión automática de la paginación

---

​

Próximos pasos

Límites de tasa

Conoce los límites de solicitudes al paginar.

SDKs

Bibliotecas con paginación integrada.