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

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

millisecond_epoch = (tweet_id >> 22) + 1288834974657

Veja dados históricos 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

Agrupe palavras centrais: (bitcoin OR ethereum OR $BTC).
Defina o conteúdo: lang:en, filter:images, -filter:replies.
Defina engajamento mínimo: min_faves:50, min_retweets:10.
Exclua ruído: -from:spambot, -scam, -filter:retweets.
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.

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, mantido por Igor Brigadir, como fonte sobre comportamentos de busca não documentados do X.

Próximos passos

Busca de publicações: endpoint completo.
Menções: monitoramento de @menções.
Paginação: grandes conjuntos de resultados.
Search Builder: construtor visual gratuito.
Guia completo no blog: receitas, código e comparação com a API v2.

Primeiros passos

Conceitos básicos

Guias práticos

Suporte e recursos

Sintaxe básica

Construtor visual gratuito

1. Palavras-chave e lógica booleana

2. Filtros de usuários e contas

3. Filtros de engajamento

4. Mídia e tipo de conteúdo

Filtros de mídia

Tipos de publicação

Conteúdo especial

5. Datas, horários e IDs Snowflake

6. Filtros geográficos

7. Idioma e aplicativo de origem

Idioma

Aplicativo de origem

8. Cards e URLs

Como montar consultas

Limitações conhecidas

Fonte

Próximos passos

​Sintaxe básica

​Construtor visual gratuito

​1. Palavras-chave e lógica booleana

​2. Filtros de usuários e contas

​3. Filtros de engajamento

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

​Filtros de mídia

​Tipos de publicação

​Conteúdo especial

​5. Datas, horários e IDs Snowflake

​6. Filtros geográficos

​7. Idioma e aplicativo de origem

​Idioma

​Aplicativo de origem

​8. Cards e URLs

​Como montar consultas

​Limitações conhecidas

​Fonte

​Próximos passos

Sintaxe básica

Construtor visual gratuito

1. Palavras-chave e lógica booleana

2. Filtros de usuários e contas

3. Filtros de engajamento

4. Mídia e tipo de conteúdo

Filtros de mídia

Tipos de publicação

Conteúdo especial

5. Datas, horários e IDs Snowflake

6. Filtros geográficos

7. Idioma e aplicativo de origem

Idioma

Aplicativo de origem

8. Cards e URLs

Como montar consultas

Limitações conhecidas

Fonte

Próximos passos