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

> Queries de busca geralmente correspondem a mais Posts do que pode ser retornado em uma única resposta da API. Referência para o tier standard da X API v2 sobre integrate.

### Paginação do recent search

#### Introdução

Queries de busca geralmente correspondem a mais Posts do que pode ser retornado em uma única resposta da API. Quando isso acontece, os dados são retornados em uma série de 'páginas'. Paginação refere-se aos métodos para solicitar todas as páginas a fim de recuperar todo o conjunto de dados.

Aqui estão os detalhes fundamentais da paginação do recent search:

* Os endpoints do recent search responderão a uma query com pelo menos uma página e fornecerão um next\_token em sua resposta JSON se páginas adicionais estiverem disponíveis. Para receber os Posts correspondentes, este processo pode ser repetido até que nenhum token seja incluído na resposta.

* O next\_token não expira. Múltiplas requisições usando o mesmo valor de next\_token receberão os mesmos resultados, independentemente de quando a requisição for feita.

* Os Posts são entregues em ordem cronológica inversa, no fuso horário UTC. Isso é verdade dentro de páginas individuais, bem como entre múltiplas páginas:
  * O primeiro Post na primeira resposta será o mais recente que corresponde à sua query.
  * O último Post na última resposta será o mais antigo que corresponde à sua query.

* O parâmetro de requisição max\_results permite configurar o número de Posts retornados por resposta. O padrão é 10 Posts e o máximo é 100.

* Toda implementação de paginação envolverá extrair next\_tokens do payload de resposta e incluí-los na requisição de busca da 'próxima página'. Veja abaixo mais detalhes sobre como construir essas requisições de 'próxima página'.

O endpoint do recent search foi projetado para suportar dois padrões fundamentais de uso:

* **Obter histórico** - Solicitar Posts correspondentes de um período de interesse. Estas são tipicamente requisições únicas em apoio à pesquisa histórica. Requisições de busca podem ser baseadas nos parâmetros de requisição start\_time e end\_time. O endpoint recent search responde com Posts entregues em ordem cronológica inversa, começando com o Post correspondente mais recente.

* **Polling** - Solicitar Posts correspondentes que foram publicados desde o último Post recebido. Estes casos de uso frequentemente têm um foco em quase tempo real e são caracterizados por requisições frequentes, "escutando" novos Posts de interesse. O endpoint recent search fornece o parâmetro de requisição since\_id em apoio ao padrão de 'polling'. Para ajudar a navegar por IDs de Post, o parâmetro de requisição until\_id também está disponível.

A seguir, discutiremos o modo histórico. Este é o modo padrão do endpoint recent search e ilustra os fundamentos da paginação. Depois discutiremos exemplos de casos de uso de polling. Quando o polling aciona a paginação, há uma etapa adicional para gerenciar as requisições de busca.

#### Recuperando dados históricos

Esta seção descreve como você pode recuperar Posts de um período de interesse (atualmente limitado aos últimos sete dias) usando os parâmetros de requisição start\_time e end\_time. Requisições históricas são tipicamente requisições únicas em apoio a pesquisa e análise.

Fazer requisições para um período de dados é o modo padrão do endpoint recent search. Se uma requisição de busca não especificar um parâmetro de requisição start\_time, end\_time ou since\_id, o end\_time será por padrão "agora" (na verdade, 30 segundos antes do momento da query) e o start\_time será por padrão sete dias atrás.

O endpoint responderá com a primeira 'página' de Posts em ordem cronológica inversa, começando com o Post mais recente. O payload JSON da resposta também incluirá um next\_token se houver páginas adicionais de dados. Para coletar o conjunto completo de Posts correspondentes, independentemente do número de páginas, requisições são feitas até que nenhum next\_token seja fornecido.

Por exemplo, aqui está uma requisição inicial para Posts com a palavra-chave snow da última semana:

[https://api.x.com/2/tweets/search/recent?query=snow](https://api.x.com/2/tweets/search/recent?query=snow)

A resposta inclui os 10 Posts mais recentes, junto com estes atributos "meta" na resposta JSON:

```
"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }
```

Para recuperar os próximos 10 Posts, este next\_token é adicionado à requisição original. A requisição seria:

[https://api.x.com/2/tweets/search/recent?query=snow\&next\_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql](https://api.x.com/2/tweets/search/recent?query=snow\&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql)

O processo de procurar um next\_token e incluí-lo em uma requisição subsequente pode ser repetido até que todos os Posts (ou algum número deles) sejam coletados, ou até que um número especificado de requisições tenha sido feito. Se a fidelidade dos dados (coletar todas as correspondências da sua query) for essencial para seu caso de uso, um design simples "repita até que request.next\_token seja null" será suficiente.

#### Casos de uso de polling e listening

Esta seção descreve como você pode recuperar Posts recentes fazendo polling no endpoint recent search com o parâmetro de requisição since\_id.

Em casos de uso de polling, queries do tipo "algum novo Post de interesse?" são feitas de forma contínua e frequente. Diferentemente dos casos de uso históricos, que baseiam requisições em tempo, casos de uso de polling normalmente baseiam requisições em IDs de Post.

Central para o padrão de uso de polling é o fato de que cada novo Post tem um [ID único](/resources/fundamentals/x-ids) que é 'emitido' pela plataforma X geralmente em ordem crescente. Se um Post tem um ID menor que outro, isso significa que foi publicado antes.

O endpoint recent search suporta navegar pelo arquivo de Posts por ID de Post. As respostas do endpoint incluem os IDs de Post oldest\_id e newest\_id. No modo de polling, as requisições são feitas com o since\_id definido como o maior/mais novo ID recebido até o momento.

Por exemplo, digamos que uma query para novos Posts sobre snow seja feita a cada cinco minutos, e o último Post que recebemos tinha um ID de Post de 10000. Na hora do polling, a requisição fica assim:

[https://api.x.com/2/tweets/search/recent?query=snow\&since\_id=10000](https://api.x.com/2/tweets/search/recent?query=snow\&since_id=10000)

A seguir, digamos que sete Posts foram publicados desde nossa última requisição. Como todos cabem em uma única 'página' de dados, não há next\_token. A resposta fornece o ID do Post mais recente (mais novo):

```
"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }
```

Para fazer a próxima query de polling, este valor de newest\_id é usado para definir o próximo parâmetro since\_id:

`https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000`

Quando há mais dados disponíveis, e next\_tokens são fornecidos, apenas o valor newest\_id da primeira página de resultados é necessário. Cada página de dados incluirá valores newest\_id e oldest\_id, mas o valor fornecido na primeira página é o único necessário para a próxima requisição de polling programada regularmente. Portanto, se você estiver implementando um design de polling ou pesquisando Posts por intervalo de ID, a lógica de paginação é um pouco mais complicada.

Agora, digamos que existem mais 18 Posts correspondentes. O endpoint responderia com esta resposta inicial com uma página completa de dados e um next\_token para solicitar a próxima página de dados deste período de cinco minutos. Também incluiria o Post ID mais novo necessário para o próximo intervalo de polling em cinco minutos.

```
"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }
```

Para coletar todos os dados correspondentes deste período de cinco minutos, passe o next\_token na sua próxima requisição, junto com o mesmo valor de since\_id da requisição anterior.

[https://api.x.com/2/tweets/search/recent?query=snow\&since\\\_id=12000\&next\\\_token=fnsih9chihsnkjbvkjbsc](https://api.x.com/2/tweets/search/recent?query=snow\&since\\_id=12000\&next\\_token=fnsih9chihsnkjbvkjbsc)

```
"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }
```

Esta segunda resposta fornece os oito Posts restantes e nenhum next\_token. Observe que não atualizamos nosso valor de newest\_id (12300) e, em vez disso, baseamos nossa próxima requisição de since\_id no valor de newest\_id da primeira resposta:

[https://api.x.com/2/tweets/search/recent?query=snow\&since\_id=13800](https://api.x.com/2/tweets/search/recent?query=snow\&since_id=13800)