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

# Operadores de busca

Os operadores do X filtram publicações por autor, data, engajamento, mídia, idioma, localização e outros atributos. A maioria funciona em `query` no endpoint [Search Tweets](https://docs.sorsa.io/pt-br/api-reference/busca/buscar-publica%C3%A7%C3%B5es) e no x.com. Os marcados como exclusivos da interface dependem da conta conectada (contas seguidas, localização ou rede) e não funcionam pela API.

> Veja receitas prontas, exemplos Python e JavaScript com paginação e comparação com a API oficial v2 no [guia completo de operadores](https://api.sorsa.io/blog/twitter-search-operators).

## Sintaxe básica

* Espaços representam **AND implícito**.
* `OR` deve estar em **maiúsculas**.
* `-` no início **exclui** um termo, frase ou operador.
* **Parênteses** agrupam expressões.
* **Aspas duplas** delimitam frases exatas.

Combine até aproximadamente 22–23 operadores por consulta. AND tem prioridade sobre OR: `cat OR black dog` equivale a `cat OR (black dog)`. Use parênteses para evitar ambiguidades.

## Construtor visual gratuito

O [Sorsa Search Builder](https://api.sorsa.io/playground/search-builder) permite selecionar filtros e visualizar a consulta antes de integrá-la ao código, sem login.

## 1. Palavras-chave e lógica booleana

| Operador             | Descrição                                                                   | Exemplo                              |
| :------------------- | :-------------------------------------------------------------------------- | :----------------------------------- |
| `keyword keyword`    | Publicações com ambos os termos (AND implícito).                            | `nasa esa`                           |
| `keyword OR keyword` | Publicações com um dos termos. OR deve estar em maiúsculas.                 | `bitcoin OR ethereum`                |
| `"exact phrase"`     | Frase exata; também impede a correção automática.                           | `"state of the art"`                 |
| `-keyword`           | Exclui o termo, a frase ou o operador.                                      | `crypto -scam`                       |
| `( )`                | Agrupa expressões booleanas.                                                | `(AI OR "machine learning") lang:en` |
| `"word * word"`      | Curinga dentro de uma frase: \* substitui uma palavra.                      | `"this is the * time"`               |
| `+word`              | Força correspondência exata, sem correção automática ou redução ao radical. | `+radiooooo`                         |
| `#hashtag`           | Hashtag específica.                                                         | `#tgif`                              |
| `$cashtag`           | Símbolo de ação ou criptomoeda.                                             | `$TSLA`                              |

Singular e plural correspondem entre si. A busca considera o texto, nome público, nome de usuário e URLs expandidas da publicação.

## 2. Filtros de usuários e contas

| Operador               | Descrição                                                                       | Exemplo                       |
| :--------------------- | :------------------------------------------------------------------------------ | :---------------------------- |
| `from:username`        | Publicações de uma conta, sem @.                                                | `from:elonmusk`               |
| `to:username`          | Respostas a uma conta.                                                          | `to:openai`                   |
| `@username`            | Menção à conta em qualquer parte do texto.                                      | `@sorsa_app`                  |
| `list:ID`              | Publicações dos membros de uma lista pública. Use o ID numérico da URL.         | `list:715919216927322112`     |
| `filter:verified`      | Contas com verificação antiga, anterior a 2023.                                 | `AI filter:verified`          |
| `filter:blue_verified` | Assinantes do X Premium (Blue pago).                                            | `crypto filter:blue_verified` |
| `filter:follows`       | Contas que você segue. Apenas na interface web; não aceita negação.             | `filter:follows`              |
| `filter:social`        | Sua rede ampliada pelo algoritmo. Apenas Top, não Latest; depende da interface. | `filter:social`               |

## 3. Filtros de engajamento

| Operador                | Descrição                                                                | Exemplo                               |
| :---------------------- | :----------------------------------------------------------------------- | :------------------------------------ |
| `min_faves:N`           | Mínimo de curtidas.                                                      | `AI min_faves:100`                    |
| `min_retweets:N`        | Mínimo de repostagens.                                                   | `crypto min_retweets:50`              |
| `min_replies:N`         | Mínimo de respostas.                                                     | `"product launch" min_replies:20`     |
| `-min_faves:N`          | Máximo de curtidas, pela forma negada.                                   | `bitcoin -min_faves:1000`             |
| `-min_retweets:N`       | Máximo de repostagens.                                                   | `news -min_retweets:500`              |
| `-min_replies:N`        | Máximo de respostas.                                                     | `tech -min_replies:100`               |
| `filter:has_engagement` | Pelo menos uma interação. Negue para buscar publicações sem engajamento. | `from:username filter:has_engagement` |

Contagens altas, acima de 1.000, tornam-se aproximadas.

## 4. Mídia e tipo de conteúdo

### Filtros de mídia

| Operador                 | Descrição                                                                                        |
| :----------------------- | :----------------------------------------------------------------------------------------------- |
| `filter:media`           | Todos os tipos de mídia: imagens, vídeos e GIFs.                                                 |
| `filter:images`          | Imagens, incluindo links de terceiros.                                                           |
| `filter:twimg`           | Somente imagens nativas do X (links pic.twitter.com).                                            |
| `filter:videos`          | Vídeos nativos, YouTube incorporado e outros.                                                    |
| `filter:native_video`    | Vídeos do X, incluindo uploads nativos e conteúdo legado de Vine e Periscope.                    |
| `filter:consumer_video`  | Vídeos nativos do X, excluindo pro/Amplify.                                                      |
| `filter:pro_video`       | Somente vídeos profissionais do X (Amplify).                                                     |
| `filter:spaces`          | Conteúdo de áudio de Spaces.                                                                     |
| `filter:links`           | Publicações com qualquer URL, inclusive de mídia. Use -filter:media para excluir links de mídia. |
| `card_name:animated_gif` | GIFs especificamente.                                                                            |

### Tipos de publicação

| Operador                 | Descrição                                                             |
| :----------------------- | :-------------------------------------------------------------------- |
| `filter:replies`         | Somente respostas a outra publicação.                                 |
| `-filter:replies`        | Exclui respostas; mostra publicações originais.                       |
| `filter:nativeretweets`  | Somente repostagens feitas pelo botão de repostar.                    |
| `include:nativeretweets` | Inclui repostagens nativas, excluídas por padrão.                     |
| `filter:retweets`        | Repostagens antigas com RT e citações.                                |
| `-filter:retweets`       | Exclui repostagens.                                                   |
| `filter:quote`           | Somente citações.                                                     |
| `quoted_tweet_id:ID`     | Citações de uma publicação pelo ID.                                   |
| `quoted_user_id:ID`      | Todas as citações de um usuário pelo ID.                              |
| `conversation_id:ID`     | Publicações de uma conversa, incluindo respostas diretas e aninhadas. |

### Conteúdo especial

| Operador                          | Descrição                                                          |
| :-------------------------------- | :----------------------------------------------------------------- |
| `card_name:poll2choice_text_only` | Enquete de texto com 2 opções.                                     |
| `card_name:poll3choice_text_only` | Enquete de texto com 3 opções.                                     |
| `card_name:poll4choice_text_only` | Enquete de texto com 4 opções.                                     |
| `card_name:poll2choice_image`     | Enquete com imagem e 2 opções.                                     |
| `filter:news`                     | Links para domínios reconhecidos de notícias.                      |
| `filter:safe`                     | Exclui conteúdo adulto ou potencialmente sensível; não é garantia. |
| `filter:hashtags`                 | Pelo menos uma hashtag.                                            |
| `filter:mentions`                 | Pelo menos uma @menção.                                            |

## 5. Datas, horários e IDs Snowflake

| Operador                        | Formato                         | Descrição                                     |
| :------------------------------ | :------------------------------ | :-------------------------------------------- |
| `since:YYYY-MM-DD`              | `since:2026-01-01`              | Publicações nesta data ou depois (inclusivo). |
| `until:YYYY-MM-DD`              | `until:2026-03-01`              | Publicações anteriores à data (exclusivo).    |
| `since:YYYY-MM-DD_HH:MM:SS_UTC` | `since:2026-03-05_12:00:00_UTC` | Data e hora precisas com fuso horário.        |
| `since_time:UNIX`               | `since_time:1142974200`         | Após um timestamp Unix em segundos.           |
| `until_time:UNIX`               | `until_time:1142974215`         | Antes de um timestamp Unix.                   |
| `within_time:Xd`                | `within_time:2d`                | Nos últimos X dias. Também aceita h, m e s.   |
| `since_id:ID`                   | `since_id:1234567890`           | Após um ID Snowflake (exclusivo).             |
| `max_id:ID`                     | `max_id:1234567890`             | Neste ID Snowflake ou antes (inclusivo).      |

**Conversão de ID Snowflake.** Cada ID codifica a data e a hora de criação:

```text theme={null}
millisecond_epoch = (tweet_id >> 22) + 1288834974657
```

Veja [dados históricos](https://docs.sorsa.io/pt-BR/historical-data) para consultar períodos anteriores.

## 6. Filtros geográficos

| Operador                  | Descrição                                             | Exemplo                             |
| :------------------------ | :---------------------------------------------------- | :---------------------------------- |
| `near:"city"`             | Geolocalização próxima a um lugar; aceita frases.     | `near:"San Francisco"`              |
| `near:me`                 | Próximo à sua localização atual; apenas na interface. | `near:me`                           |
| `within:Xkm`              | Raio de near:, em km ou mi.                           | `earthquake near:Tokyo within:50km` |
| `geocode:lat,long,radius` | Coordenadas e raio específicos.                       | `geocode:37.77,-122.41,5km`         |
| `place:ID`                | Busca por ID de um objeto Place do X.                 | `place:96683cc9126741d1`            |

Estima-se que apenas 1–2% das publicações tenham coordenadas precisas. Sem coordenadas, a API recorre à geocodificação reversa da localização declarada no perfil.

## 7. Idioma e aplicativo de origem

### Idioma

Use códigos ISO 639-1 como `lang:en`, `lang:es`, `lang:fr`, `lang:de`, `lang:ja` e `lang:ru`, ou os códigos específicos do X:

| Código     | Significado                                           |
| :--------- | :---------------------------------------------------- |
| `lang:und` | Idioma indefinido, como posts só com emojis ou mídia. |
| `lang:qme` | Somente links de mídia (desde 2022).                  |
| `lang:qst` | Texto muito curto.                                    |
| `lang:qht` | Somente hashtags.                                     |
| `lang:qam` | Somente menções.                                      |
| `lang:qct` | Somente cashtags.                                     |
| `lang:zxx` | Somente mídia ou Twitter Card, sem texto.             |

### Aplicativo de origem

| Operador             | Descrição                                                                      | Exemplo                     |
| :------------------- | :----------------------------------------------------------------------------- | :-------------------------- |
| `source:client_name` | Filtra pelo aplicativo usado para publicar. Substitua espaços por sublinhados. | `source:Twitter_for_iPhone` |

Valores comuns: `Twitter_for_iPhone`, `Twitter_for_Android`, `Twitter_Web_App`, `TweetDeck` e `twitter_ads`.

## 8. Cards e URLs

| Operador                        | Descrição                                                                                 |
| :------------------------------ | :---------------------------------------------------------------------------------------- |
| `card_domain:domain`            | Domínio em um Twitter Card; semelhante a url:.                                            |
| `card_url:domain`               | Semelhante a card\_domain:, mas pode retornar outros resultados.                          |
| `card_name:audio`               | Player Cards de áudio, como Spotify e SoundCloud.                                         |
| `card_name:player`              | Qualquer Player Card.                                                                     |
| `card_name:summary`             | Cards de resumo com imagem pequena.                                                       |
| `card_name:summary_large_image` | Cards de resumo com imagem grande.                                                        |
| `card_name:promo_website`       | Cards de sites promovidos.                                                                |
| `card_name:promo_image_convo`   | Cards de anúncios de conversa com imagens.                                                |
| `card_name:promo_video_convo`   | Cards de anúncios de conversa com vídeo.                                                  |
| `url:domain`                    | URLs por domínio ou subdomínio. Substitua hífens por sublinhados, como url:t\_mobile.com. |

`card_name:` normalmente só encontra publicações dos últimos 7–8 dias.

## Como montar consultas

1. **Agrupe palavras centrais:** `(bitcoin OR ethereum OR $BTC)`.
2. **Defina o conteúdo:** `lang:en`, `filter:images`, `-filter:replies`.
3. **Defina engajamento mínimo:** `min_faves:50`, `min_retweets:10`.
4. **Exclua ruído:** `-from:spambot`, `-scam`, `-filter:retweets`.
5. **Delimite o período:** `since:2026-01-01 until:2026-03-01`.

Veja 14 receitas de consulta e exemplos completos com paginação e tratamento de limites no [blog](https://api.sorsa.io/blog/twitter-search-operators).

## Limitações conhecidas

* Máximo aproximado de 22–23 operadores por consulta.
* Só 1–2% das publicações têm localização precisa.
* `card_name:` se limita aos últimos 7–8 dias.
* Contas privadas e suspensas são excluídas.
* A detecção de idioma pode falhar em textos curtos, código ou muitos emojis.
* Nem toda publicação é indexada; conteúdo marcado por violações pode ser excluído.
* A correção automática pode ocorrer silenciosamente. Use `+word` ou `"word"` para correspondência exata.
* A busca de URLs funciona melhor para domínios e subdomínios que para caminhos longos.

## Fonte

Esta referência usa o repositório [twitter-advanced-search](https://github.com/igorbrigadir/twitter-advanced-search), mantido por Igor Brigadir, como fonte sobre comportamentos de busca não documentados do X.

## Próximos passos

* [Busca de publicações](https://docs.sorsa.io/pt-BR/search-tweets): endpoint completo.
* [Menções](https://docs.sorsa.io/pt-BR/search-mentions): monitoramento de @menções.
* [Paginação](https://docs.sorsa.io/pt-BR/pagination): grandes conjuntos de resultados.
* [Search Builder](https://api.sorsa.io/playground/search-builder): construtor visual gratuito.
* [Guia completo no blog](https://api.sorsa.io/blog/twitter-search-operators): receitas, código e comparação com a API v2.