Paginación

Cuando solicitas una lista de elementos a Sorsa API, los resultados se devuelven por páginas. Para recuperar el conjunto completo, recorre las páginas mediante cursores hasta que no queden datos.

Cómo funciona la paginación por cursor

Sorsa utiliza cursores en lugar de números de página. Este método es más fiable para datos sociales, donde se añade contenido continuamente y la paginación por desplazamiento puede omitir o duplicar resultados. El procedimiento es el mismo en todos los endpoints paginados:

Envía la primera solicitud sin cursor.
La respuesta incluye los datos y un campo next_cursor.
Envía ese valor en la siguiente solicitud para obtener la próxima página.
Si next_cursor es null o no aparece, has llegado al final.

No todos los endpoints usan paginación. /info, /tweet-info, /score y /about devuelven un único objeto y no tienen cursor. Algunas listas también se devuelven en una sola respuesta, como /info-batch, /tweet-info-bulk y las listas de análisis de criptomonedas como /top-followers. Comprueba en la referencia si el endpoint admite next_cursor.

Estructura de las respuestas

Las respuestas paginadas siguen uno de estos dos patrones:

{
  "users": [ ... ],
  "next_cursor": "DAABCgABF7Y..."
}

{
  "tweets": [ ... ],
  "next_cursor": "DAABCgABF7Y..."
}

En estas respuestas, los datos están en users o tweets. Trata next_cursor como un valor opaco: devuélvelo sin cambios y detente cuando sea nulo, esté vacío o no aparezca. No incrementes el cursor ni lo conviertas a un Number de JavaScript. Consulta las estructuras y los esquemas de objetos en Formato de respuesta.

Cómo enviar los cursores

El campo siempre se llama next_cursor. Solo cambia dónde se envía: como parámetro de consulta en GET y dentro del cuerpo JSON en POST. Endpoints GET, como /followers, /follows y /list-tweets:

# First page
curl --request GET \
  --url 'https://api.sorsa.io/v3/followers?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'

# Next page
curl --request GET \
  --url 'https://api.sorsa.io/v3/followers?username=elonmusk&next_cursor=DAABCgABF7Y...' \
  --header 'ApiKey: YOUR_API_KEY'

Endpoints POST, como /search-tweets, /user-tweets y /comments:

# First page
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin"}'

# Next page
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "next_cursor": "DAABCgABF7Y..."}'

El tamaño de las páginas no es fijo

La cantidad de resultados por página puede variar debido a la naturaleza de los datos de X. Un endpoint que devuelve hasta 20 elementos puede devolver 18, 12 o incluso 5 en una página, aunque haya más datos en la siguiente. No utilices la cantidad de elementos para decidir si has llegado al final. Una página con menos resultados de los esperados no indica que se hayan agotado los datos. Comprueba siempre next_cursor: si existe y no es null, quedan páginas por consultar.

Ejemplos completos de paginación

Estos ejemplos acumulan los resultados en memoria. Para trabajos grandes, guarda cada página, elimina duplicados por ID de cadena y registra un punto de reanudación después de almacenarla. Mantén la misma cuenta, consulta, filtros y orden mientras utilices un cursor. Establece un presupuesto de páginas o solicitudes y detecta cursores repetidos para evitar bucles interminables. Una pausa en un bucle no coordina los demás procesos que comparten la clave. Python: recorrer seguidores (GET)

import time
import requests

API_KEY = "YOUR_API_KEY"

def fetch_all_followers(username):
    all_users = []
    cursor = None

    while True:
        params = {"username": username}
        if cursor:
            params["next_cursor"] = cursor

        response = requests.get(
            "https://api.sorsa.io/v3/followers",
            params=params,
            headers={"ApiKey": API_KEY},
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()

        users = data.get("users", [])
        all_users.extend(users)
        print(f"Page fetched: {len(users)} users. Total so far: {len(all_users)}")

        cursor = data.get("next_cursor")
        if not cursor:
            break

        time.sleep(0.05)  # respect 20 req/s rate limit

    return all_users

followers = fetch_all_followers("elonmusk")
print(f"Done. {len(followers)} followers total.")

Python: recorrer resultados de búsqueda (POST)

import time
import requests

API_KEY = "YOUR_API_KEY"

def search_all_tweets(query):
    all_tweets = []
    cursor = None

    while True:
        body = {"query": query}
        if cursor:
            body["next_cursor"] = cursor

        response = requests.post(
            "https://api.sorsa.io/v3/search-tweets",
            json=body,
            headers={"ApiKey": API_KEY},
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()

        tweets = data.get("tweets", [])
        all_tweets.extend(tweets)
        print(f"Page fetched: {len(tweets)} tweets. Total so far: {len(all_tweets)}")

        cursor = data.get("next_cursor")
        if not cursor:
            break

        time.sleep(0.05)

    return all_tweets

results = search_all_tweets("bitcoin")
print(f"Done. {len(results)} tweets total.")

JavaScript: recorrer seguidores (GET)

async function fetchAllFollowers(username) {
  const API_KEY = "YOUR_API_KEY";
  const allUsers = [];
  let cursor = null;

  while (true) {
    const params = new URLSearchParams({ username });
    if (cursor) params.append("next_cursor", cursor);

    const response = await fetch(
      `https://api.sorsa.io/v3/followers?${params}`,
      { headers: { "ApiKey": API_KEY } }
    );
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();

    const users = data.users || [];
    allUsers.push(...users);
    console.log(`Page fetched: ${users.length} users. Total: ${allUsers.length}`);

    cursor = data.next_cursor;
    if (!cursor) break;

    await new Promise(r => setTimeout(r, 50));
  }

  return allUsers;
}

JavaScript: recorrer resultados de búsqueda (POST)

async function searchAllTweets(query) {
  const API_KEY = "YOUR_API_KEY";
  const allTweets = [];
  let cursor = null;

  while (true) {
    const body = { query };
    if (cursor) body.next_cursor = cursor;

    const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
      method: "POST",
      headers: {
        "ApiKey": API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(body)
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();

    const tweets = data.tweets || [];
    allTweets.push(...tweets);
    console.log(`Page fetched: ${tweets.length} tweets. Total: ${allTweets.length}`);

    cursor = data.next_cursor;
    if (!cursor) break;

    await new Promise(r => setTimeout(r, 50));
  }

  return allTweets;
}

Paginación con gestión de errores

En producción, combina la paginación con reintentos para que el fallo de una página no interrumpa toda la recopilación. Consulta la referencia completa en Códigos de error.

import time
import requests

API_KEY = "YOUR_API_KEY"

def paginate_with_retries(username, max_retries=3):
    all_users = []
    cursor = None

    while True:
        params = {"username": username}
        if cursor:
            params["next_cursor"] = cursor

        for attempt in range(max_retries):
            response = requests.get(
                "https://api.sorsa.io/v3/followers",
                params=params,
                headers={"ApiKey": API_KEY},
                timeout=30,
            )

            if response.status_code == 200:
                break
            elif response.status_code == 429:
                time.sleep(1)
                continue
            elif response.status_code >= 500:
                time.sleep(2)
                continue
            else:
                raise Exception(f"Error {response.status_code}: {response.text}")
        else:
            raise Exception("Max retries exceeded")

        data = response.json()
        all_users.extend(data.get("users", []))

        cursor = data.get("next_cursor")
        if not cursor:
            break

        time.sleep(0.05)

    return all_users

Próximos pasos

Límites de solicitudes: cómo respetar las 20 solicitudes por segundo al recorrer grandes conjuntos de datos.
Códigos de error: gestión de errores 429 y otros fallos en los bucles de paginación.
Formato de respuesta: esquemas completos de User y Tweet.

Primeros pasos

Conceptos básicos

Guías prácticas

Soporte y recursos

Cómo funciona la paginación por cursor

Estructura de las respuestas

Cómo enviar los cursores

El tamaño de las páginas no es fijo

Ejemplos completos de paginación

Paginación con gestión de errores

Próximos pasos

​Cómo funciona la paginación por cursor

​Estructura de las respuestas

​Cómo enviar los cursores

​El tamaño de las páginas no es fijo

​Ejemplos completos de paginación

​Paginación con gestión de errores

​Próximos pasos

Cómo funciona la paginación por cursor

Estructura de las respuestas

Cómo enviar los cursores

El tamaño de las páginas no es fijo

Ejemplos completos de paginación

Paginación con gestión de errores

Próximos pasos