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

# Busca de publicações

> Endpoint POST para buscar publicações do X (Twitter) por palavras-chave e operadores.

`/search-tweets` consulta o índice público de busca do X e retorna publicações com perfis completos dos autores e métricas de engajamento. Veja fluxos completos, modelos de consulta e código no [guia de busca de publicações](https://api.sorsa.io/blog/twitter-search-api), no blog.

## Endpoint

```text theme={null}
POST https://api.sorsa.io/v3/search-tweets
```

## Autenticação

Envie a chave no cabeçalho `ApiKey`. O nome do cabeçalho não diferencia maiúsculas de minúsculas; o valor deve ser exatamente o da chave emitida.

```text theme={null}
ApiKey: YOUR_API_KEY
```

Veja [autenticação](https://docs.sorsa.io/pt-BR/authentication).

## Corpo da requisição

| Parâmetro     | Tipo   | Obrigatório | Descrição                                                                          |
| :------------ | :----- | :---------- | :--------------------------------------------------------------------------------- |
| `query`       | string | Sim         | Palavras-chave e operadores nativos de busca do X.                                 |
| `order`       | string | Não         | `"popular"` (padrão), equivalente à aba Top, ou `"latest"` para ordem cronológica. |
| `next_cursor` | string | Não         | Cursor da resposta anterior. Omita na primeira chamada.                            |

### Exemplo

```bash theme={null}
curl -X POST https://api.sorsa.io/v3/search-tweets \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence lang:en",
    "order": "latest"
  }'
```

## Resposta

```json theme={null}
{
  "tweets": [
    {
      "id": "2029914600217473314",
      "full_text": "The latest breakthroughs in AI are reshaping automation.",
      "created_at": "2026-03-06T13:38:49Z",
      "lang": "en",
      "conversation_id_str": "2029914600217473314",
      "likes_count": 142,
      "retweet_count": 38,
      "reply_count": 12,
      "quote_count": 5,
      "view_count": 28400,
      "bookmark_count": 19,
      "is_reply": false,
      "is_quote_status": false,
      "entities": [],
      "user": {
        "id": "1422280682240450563",
        "username": "tech_insider",
        "display_name": "Tech Insider",
        "followers_count": 84200,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkAAgoAAgjEJ..."
}
```

Cada publicação inclui o perfil completo do autor. Não é necessária outra consulta para obter seus dados. Veja os campos em [formato de resposta](https://docs.sorsa.io/pt-BR/response-format).

## Operadores

O campo `query` aceita os operadores nativos do X:

* **Palavras e frases exatas:** `"climate change"`.
* **Usuários:** `from:`, `to:`, `@mention`.
* **Engajamento:** `min_faves:`, `min_retweets:`, `min_replies:`.
* **Conteúdo:** `filter:media`, `filter:images`, `filter:videos`, `filter:links`; use `-` para excluir.
* **Idioma e data:** `lang:en`, `since:2026-01-01`, `until:2026-03-01`.
* **Lógica booleana:** `OR`, parênteses e `-`.

Consulte a referência de [operadores de busca](https://docs.sorsa.io/pt-BR/search-operators).

## Paginação

Repita a mesma consulta com o `next_cursor` retornado. Quando ele for nulo ou ausente, os resultados terminaram. Veja [paginação](https://docs.sorsa.io/pt-BR/pagination).

## Limite de requisições

20 requisições por segundo por chave em todos os planos padrão. O excesso retorna `429 Too Many Requests`. Veja [limites](https://docs.sorsa.io/pt-BR/rate-limits).

## Códigos de erro

| Código | Significado                          |
| :----- | :----------------------------------- |
| `200`  | OK                                   |
| `400`  | Parâmetros inválidos                 |
| `401`  | Chave ausente ou inválida            |
| `403`  | Cota esgotada ou assinatura expirada |
| `429`  | Limite de frequência excedido        |
| `500`  | Erro interno                         |

Veja [códigos de erro](https://docs.sorsa.io/pt-BR/error-codes).

## Endpoints relacionados

* [Menções](https://docs.sorsa.io/pt-br/api-reference/busca/buscar-men%C3%A7%C3%B5es): monitoramento de `@handle` com filtros no corpo.
* [Publicações de usuário](https://docs.sorsa.io/pt-br/api-reference/publica%C3%A7%C3%B5es/publica%C3%A7%C3%B5es-do-usu%C3%A1rio): timeline de uma conta.
* [Busca de usuários](https://docs.sorsa.io/pt-br/api-reference/busca/buscar-usu%C3%A1rios): contas por palavra-chave.