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

# Dados históricos

A Sorsa oferece acesso ao arquivo de dados públicos do X desde março de 2006. Consultas históricas usam os mesmos endpoints, autenticação e paginação das recentes, sem faixa separada de arquivo completo, contrato empresarial ou restrição de janela de busca. Elas consomem a mesma cota e podem ser testadas com as 100 requisições gratuitas, sem cartão.

Este guia descreve os endpoints, os dados disponíveis e os padrões para grandes consultas. Veja comparação de métodos, exportação CSV e outros exemplos no [guia do blog](https://api.sorsa.io/blog/historical-twitter-data).

## Endpoints

| Endpoint                 | Uso                                                   | Paginação     | Tamanho da página |
| :----------------------- | :---------------------------------------------------- | :------------ | :---------------- |
| `POST /v3/search-tweets` | Busca histórica por palavra-chave, data e engajamento | `next_cursor` | \~20 publicações  |
| `POST /v3/user-tweets`   | Histórico de publicações de uma conta                 | `next_cursor` | \~20 publicações  |

`/search-tweets` aceita os [operadores do X](https://docs.sorsa.io/pt-BR/search-operators), incluindo `since:`, `until:`, `from:`, `to:`, `min_faves:`, `min_retweets:`, `lang:` e `filter:`, dentro de `query`. `/user-tweets` recebe apenas um identificador (`user_link`, `username` ou `user_id`) e retorna a timeline sem filtros de consulta.

## Busca histórica por palavra-chave

Use `/search-tweets` para buscar em todas as contas dentro de um período:

```python theme={null}
import requests, time

API_KEY = "YOUR_API_KEY"
URL = "https://api.sorsa.io/v3/search-tweets"

def search_archive(query, max_pages=50):
    all_tweets, next_cursor = [], None
    for _ in range(max_pages):
        body = {"query": query, "order": "latest"}
        if next_cursor:
            body["next_cursor"] = next_cursor

        resp = requests.post(
            URL,
            headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
            json=body,
        )
        resp.raise_for_status()
        data = resp.json()

        all_tweets.extend(data.get("tweets", []))
        next_cursor = data.get("next_cursor")
        if not next_cursor:
            break
        time.sleep(0.1)
    return all_tweets


tweets = search_archive('"climate change" since:2015-06-01 until:2015-12-31 lang:en min_faves:10')
```

`order` aceita `"latest"` (cronológico) ou `"popular"` (engajamento). Use latest para coleta por período e popular para encontrar conteúdo de maior engajamento.

## Timeline completa de uma conta

`/user-tweets` percorre do mais recente ao mais antigo, sem limite de 3.200 publicações.

```python theme={null}
resp = requests.post(
    "https://api.sorsa.io/v3/user-tweets",
    headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
    json={"user_link": "https://x.com/naval"},
)
```

Envie exatamente um identificador e percorra `next_cursor` até ficar nulo. Para limitar uma conta por datas, use busca com `from:`, como `from:naval since:2020-01-01 until:2021-01-01`. `/user-tweets` não aceita filtros de data.

## Dados retornados

Publicações históricas têm os mesmos campos das recentes:

* Texto completo, sem truncamento ou substituição de URLs.
* `likes_count`, `retweet_count`, `reply_count`, `quote_count`, `view_count` e `bookmark_count`.
* Perfil completo do autor em `user`.
* Mídias e prévias de links em `entities`.
* `conversation_id_str`, `in_reply_to_tweet_id`, `is_reply` e `is_quote_status`.
* Idioma em `lang`.

Veja [formato de resposta](https://docs.sorsa.io/pt-BR/response-format).

## Limitações da plataforma

São restrições do X, não específicas da Sorsa:

* **Publicações excluídas** saem do índice e não podem ser recuperadas.
* **Contas protegidas** não aparecem em buscas públicas ou timelines.
* **Perfis não são históricos.** Uma publicação de 2014 traz bio, nome e seguidores atuais.
* **Métricas não são retratos do passado.** Curtidas, repostagens e visualizações mostram os totais atuais. Para séries históricas de métricas, capture e armazene os dados com [monitoramento em tempo real](https://docs.sorsa.io/pt-BR/real-time-monitoring).

## Boas práticas

### Divida períodos grandes

Uma consulta de vários anos dificulta retomadas e auditoria por período. Divida por mês em coletas anuais e por semana em eventos intensos.

```python theme={null}
def monthly_chunks(year):
    out = []
    for month in range(1, 13):
        since = f"{year}-{month:02d}-01"
        nm = month + 1 if month < 12 else 1
        ny = year if month < 12 else year + 1
        until = f"{ny}-{nm:02d}-01"
        out.append((since, until))
    return out

for since, until in monthly_chunks(2020):
    tweets = search_archive(f'bitcoin since:{since} until:{until} lang:en min_faves:50')
```

### Reduza o ruído de repostagens

Use `-filter:nativeretweets` para pesquisar sentimento, opiniões ou padrões de conteúdo original. `-filter:retweets` também exclui repostagens antigas no formato RT.

### Combine datas e engajamento

`since:`/`until:` com `min_faves:` ou `min_retweets:` reduz ruído e consumo.

```text theme={null}
"product launch" since:2022-03-01 until:2022-03-31 min_faves:100 -filter:retweets lang:en
```

### Separe temas globais por idioma

Consultas distintas com `lang:` produzem conjuntos por idioma mais organizados.

### Continue até o fim do cursor

Pare apenas quando `next_cursor` estiver nulo, vazio ou ausente, não quando a página tiver poucos itens. Veja [paginação](https://docs.sorsa.io/pt-BR/pagination).

## Relacionados

* [Busca](https://docs.sorsa.io/pt-BR/search-tweets): referência do endpoint.
* [Operadores](https://docs.sorsa.io/pt-BR/search-operators): dicionário completo.
* [Paginação](https://docs.sorsa.io/pt-BR/pagination): cursores.
* [Monitoramento em tempo real](https://docs.sorsa.io/pt-BR/real-time-monitoring): combine histórico e coleta contínua.
* [Menções](https://docs.sorsa.io/pt-BR/search-mentions): menções históricas.
* [Otimização](https://docs.sorsa.io/pt-BR/optimizing-api-usage): reduza o consumo.