Criar uma regra

Os endpoints do filtered stream entregam Posts que correspondem a um conjunto de regras aplicadas ao stream. As regras são compostas por operadores que correspondem a diversos atributos de Post. Múltiplas regras podem ser aplicadas usando o endpoint POST /tweets/search/stream/rules. Uma vez que você tenha adicionado regras e se conectado usando GET /tweets/search/stream, apenas Posts que correspondam às suas regras serão entregues. Você não precisa se desconectar para adicionar ou remover regras.

Limitações de regras

Os limites de número de regras dependem do seu nível de acesso. Consulte a introdução do filtered stream para limites específicos.

Tipos de operador: independentes e que exigem conjunção

Operadores independentes podem ser usados sozinhos ou junto com quaisquer outros operadores (incluindo os que exigem conjunção). Por exemplo, esta regra funciona porque #hashtag é um operador independente:

#xapiv2

Operadores que exigem conjunção não podem ser usados sozinhos em uma regra; só podem ser usados quando pelo menos um operador independente estiver incluído. Isso ocorre porque usar esses operadores sozinhos corresponderia a um volume extremamente alto de Posts. Por exemplo, as seguintes regras não são suportadas, pois contêm apenas operadores que exigem conjunção:

has:media

has:links OR is:retweet

embedding_threshold:0.45

Se adicionarmos um operador independente, como a frase "X data", a regra funciona corretamente:

"X data" has:mentions (has:media OR has:links)

O operador embedding_threshold: (usado com regras semânticas embedding:) também exige conjunção.

Operadores booleanos e agrupamento

Combine múltiplos operadores usando estas ferramentas:

Operador	Descrição	Exemplo
AND (espaço)	Posts devem corresponder a ambas as condições	`snow day #NoSchool` corresponde a Posts com “snow” AND “day” AND #NoSchool
OR	Posts devem corresponder a qualquer condição	`grumpy OR cat OR #meme` corresponde a Posts com “grumpy” OR “cat” OR #meme
NOT (traço)	Excluir Posts que correspondam a esta condição	`cat #meme -grumpy` corresponde a Posts com “cat” e #meme mas NOT “grumpy”
Agrupamento (parênteses)	Agrupar operadores	`(grumpy cat) OR (#meme has:images)` corresponde a qualquer grupo

Uma nota sobre negações

Todos os operadores podem ser negados, exceto sample: e embedding:
O operador -is:nullcast deve sempre ser negado
Operadores negados não podem ser usados sozinhos
Não negue operadores agrupados. Em vez de skiing -(snow OR day OR noschool), use skiing -snow -day -noschool
Escrever -embedding:"query" não é suportado

Ordem das operações

Ao combinar AND e OR:

Operadores conectados por lógica AND são combinados primeiro
Em seguida, operadores conectados com lógica OR são aplicados

Exemplos:

Query	Avaliada como
`apple OR iphone ipad`	`apple OR (iphone ipad)`
`ipad iphone OR android`	`(iphone ipad) OR android`

Para eliminar incertezas, use parênteses:

(apple OR iphone) ipad

iphone (ipad OR android)

Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

Diacríticos: Regras do filtered stream com acentos correspondem apenas a Posts que também incluam o acento. Por exemplo, diacrítica corresponde a diacrítica mas não a diacritica. Sensibilidade a maiúsculas/minúsculas: Todos os operadores são insensíveis a maiúsculas/minúsculas. A regra cat corresponde a cat, CAT e Cat.

Search Posts se comporta de forma diferenteAo criar queries de busca, palavras-chave com acentos correspondem tanto a Posts com quanto sem os acentos. Por exemplo, Diacrítica corresponde tanto a Diacrítica quanto a Diacritica.

Correspondência de Quote Tweet

Ao usar filtered stream, os operadores correspondem tanto ao conteúdo do Quote Tweet quanto ao conteúdo do Post original que foi citado.

Search Posts se comporta de forma diferente — corresponde apenas ao conteúdo do Quote Tweet, não ao do Post original.

Especificidade e eficiência

Usar operadores amplos como uma única palavra-chave ou hashtag não é recomendado — isso corresponderá a um volume enorme de Posts e consumirá rapidamente sua conexão.

Dicas para criar regras eficazes:

Comece específico e depois amplie — Crie regras direcionadas que retornem resultados relevantes
Use múltiplos operadores — Combine operadores para restringir resultados
Fique atento à contagem de caracteres — Toda a string da regra conta para o limite

Exemplo de progressão:

# Muito amplo - 200.000+ Posts por dia
happy

# Melhor - adiciona filtro de idioma e exclusões
(happy OR happiness) lang:en -birthday -is:retweet

# Ainda melhor - 59 caracteres, mais específico
(happy OR happiness) place_country:GB -birthday -is:retweet

Construindo uma regra iterativamente

Passo 1: Comece com uma regra básica

happy OR happiness

Passo 2: Teste e refine com base nos resultados

Notamos Posts em vários idiomas. Adicione um filtro de idioma:

(happy OR happiness) lang:en

Estamos recebendo felicitações de aniversário. Exclua-as e os Retweets:

(happy OR happiness) lang:en -birthday -is:retweet

Passo 3: Amplie para melhor cobertura

Queremos capturar mais sentimento. Adicione palavras-chave relacionadas:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

Passo 4: Ajuste para tendências

Posts de feriados estão aparecendo. Exclua-os:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

Adicionando e removendo regras

Use POST /2/tweets/search/stream/rules para adicionar ou remover regras.

Adicionando regras

Envie um corpo JSON add com o value (a regra) e um tag opcional (para identificar os Posts correspondentes):

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "add": [
      {"value": "cat has:media", "tag": "cats with media"},
      {"value": "cat has:media -grumpy", "tag": "happy cats with media"},
      {"value": "meme", "tag": "funny things"},
      {"value": "meme has:images"}
    ]
  }'

Removendo regras

Envie um corpo JSON delete com os IDs das regras a remover:

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "delete": {
      "ids": [
        "1165037377523306498",
        "1165037377523306499"
      ]
    }
  }'

Exemplos de regras

Acompanhando um desastre natural

Corresponde a Posts de agências meteorológicas sobre o Furacão Harvey:

{
  "value": "-is:retweet has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1)",
  "tag": "Hurricane Harvey - weather agencies with geo"
}

Análise de sentimento para #nowplaying

Sentimento positivo:

{
  "value": "#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing",
  "tag": "#nowplaying positive"
}

Sentimento negativo:

{
  "value": "#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible",
  "tag": "#nowplaying negative"
}

Usando Post annotations

Encontre Posts em japonês sobre pets (não gatos) com imagens usando o operador context:: Primeiro, use o Post lookup com tweet.fields=context_annotations para identificar IDs de domain.entity:

Gatos: domain 66, entity 852262932607926273
Pets: domain 65, entity 852262932607926273

{
  "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
  "tag": "Japanese pets with images - no cats"
}

Correspondência semântica com embeddings (Enterprise)

Use o operador embedding: para corresponder Posts pelo significado conceitual em vez de palavras-chave. Isso requer Enterprise + tier de Embedding.

{
  "value": "embedding:\"climate change policy\" embedding_threshold:0.4",
  "tag": "climate-semantic"
}

Combine com operadores estruturais para maior precisão:

{
  "value": "embedding:\"quarterly earnings surprises\" lang:en has:links -is:retweet",
  "tag": "earnings-en"
}

Consulte a referência de operadores para detalhes completos e melhores práticas.

Próximos passos

Referência de operadores

Lista completa dos operadores disponíveis

Quickstart do filtered stream

Conecte-se ao seu stream

Código de exemplo

Exemplos de código em várias linguagens

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Criar uma regra

Limitações de regras

Tipos de operador: independentes e que exigem conjunção

Operadores booleanos e agrupamento

Ordem das operações

Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

Correspondência de Quote Tweet

Especificidade e eficiência

Construindo uma regra iterativamente

Passo 1: Comece com uma regra básica

Passo 2: Teste e refine com base nos resultados

Passo 3: Amplie para melhor cobertura

Passo 4: Ajuste para tendências

Adicionando e removendo regras

Adicionando regras

Removendo regras

Exemplos de regras

Acompanhando um desastre natural

Análise de sentimento para #nowplaying

Usando Post annotations

Correspondência semântica com embeddings (Enterprise)

Próximos passos

Referência de operadores

Quickstart do filtered stream

Código de exemplo

​Limitações de regras

​Tipos de operador: independentes e que exigem conjunção

​Operadores booleanos e agrupamento

​Ordem das operações

​Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

​Correspondência de Quote Tweet

​Especificidade e eficiência

​Construindo uma regra iterativamente

​Passo 1: Comece com uma regra básica

​Passo 2: Teste e refine com base nos resultados

​Passo 3: Amplie para melhor cobertura

​Passo 4: Ajuste para tendências

​Adicionando e removendo regras

​Adicionando regras

​Removendo regras

​Exemplos de regras

​Acompanhando um desastre natural

​Análise de sentimento para #nowplaying

​Usando Post annotations

​Correspondência semântica com embeddings (Enterprise)

​Próximos passos

Referência de operadores

Quickstart do filtered stream

Código de exemplo

Limitações de regras

Tipos de operador: independentes e que exigem conjunção

Operadores booleanos e agrupamento

Ordem das operações

Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

Correspondência de Quote Tweet

Especificidade e eficiência

Construindo uma regra iterativamente

Passo 1: Comece com uma regra básica

Passo 2: Teste e refine com base nos resultados

Passo 3: Amplie para melhor cobertura

Passo 4: Ajuste para tendências

Adicionando e removendo regras

Adicionando regras

Removendo regras

Exemplos de regras

Acompanhando um desastre natural

Análise de sentimento para #nowplaying

Usando Post annotations

Correspondência semântica com embeddings (Enterprise)

Próximos passos