> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginação

> Pagine resultados da X API em Python usando o iterador do XDK para tratamento automático de next_token, ou gerencie pagination_token manualmente para uma lógica de paginação personalizada.

A X API usa paginação para endpoints que retornam múltiplas páginas de resultados (por exemplo, timelines, pesquisa etc.). Cada resposta de chamada de API inclui um objeto `meta` com `result_count`, `previous_token` e `next_token`. O XDK cuida de fazer múltiplas chamadas de API usando o `next_token`, para que os desenvolvedores possam apenas especificar quanto dados desejam sem precisar fazer múltiplas chamadas.
O SDK simplifica isso com:

* **Iteradores integrados**: Use funções geradoras para busca contínua de múltiplas páginas.
* **Tratamento explícito de tokens**: Para controle manual flexível quando necessário, passando `pagination_token` conforme apropriado.
* **Aplicação de Max Results**: Respeita `max_results` por chamada (até os limites da API, por exemplo, 100 para pesquisa).

## Paginação automática (recomendado)

Use o método `iterate()` em respostas paginadas para buscar todos os resultados de forma preguiçosa.
**Exemplo: pesquisa paginada**

```python title="Example" lines wrap icon="python" theme={null}
from xdk import Client
client = Client(bearer_token="your_bearer_token")
# Search with automatic pagination
all_posts = []
for page in client.posts.search_recent(
    query="python",
    max_results=100,  # Per page
    tweet_fields=["created_at", "author_id"]  # Optional expansions
):
    all_posts.extend(page.data)
    print(f"Fetched {len(page.data)} Posts (total: {len(all_posts)})")
print(f"Total tweets: {len(all_posts)}")
```

* O iterador trata `next_token` automaticamente.
* Para quando não há um `next_token` presente.
* Suporta backoff de limite de taxa para evitar erros 429.

## Paginação manual

Se você precisar controlar os resultados para alguma lógica personalizada (por exemplo, processando página por página), ainda pode usar o `next_token` e fazer a paginação manualmente, como mostrado abaixo:

```python title="Example" lines wrap icon="python" theme={null}
# Get first page - search_recent returns an Iterator
first_page = next(client.posts.search_recent(
    query="xdk python sdk",
    max_results=100,
    pagination_token=None  # First page
))
print(f"First page: {len(first_page.data) if first_page.data else 0} Posts")
# Extract next_token from meta
next_token = None
if hasattr(first_page, 'meta') and first_page.meta:
    if hasattr(first_page.meta, 'next_token'):
        next_token = first_page.meta.next_token
    elif isinstance(first_page.meta, dict):
        next_token = first_page.meta.get('next_token')
if next_token:
    second_page = next(client.posts.search_recent(
        query="xdk python sdk",
        max_results=100,
        pagination_token=next_token
    ))
    print(f"Second page: {len(second_page.data) if second_page.data else 0} Posts")
```

**Dicas**:

* Sempre especifique `max_results` para otimizar (o padrão varia por endpoint).
* Monitore `meta.result_count` para depuração.
* Para consultas muito grandes, considere iteração assíncrona para evitar bloqueios.
  Para exemplos de código detalhados usando o XDK Python, confira nosso [repositório de exemplos de código no GitHub](https://github.com/xdevplatform/samples/tree/main/python).