Construir una regla

Los endpoints de filtered stream entregan Posts que coinciden con un conjunto de reglas aplicadas al stream. Las reglas están compuestas por operadores que coinciden con una variedad de atributos de Post. Se pueden aplicar múltiples reglas usando el endpoint POST /tweets/search/stream/rules. Una vez que hayas agregado reglas y te hayas conectado usando GET /tweets/search/stream, solo se entregarán los Posts que coincidan con tus reglas. No necesitas desconectarte para añadir o eliminar reglas.

Limitaciones de las reglas

Los límites del número de reglas dependen de tu nivel de acceso. Consulta la introducción a filtered stream para conocer los límites específicos.

Tipos de operadores: independientes y que requieren conjunción

Los operadores independientes pueden usarse solos o junto con cualquier otro operador (incluidos aquellos que requieren conjunción). Por ejemplo, esta regla funciona porque #hashtag es un operador independiente:

#xapiv2

Los operadores que requieren conjunción no pueden usarse solos en una regla; solo pueden usarse cuando se incluye al menos un operador independiente. Esto se debe a que usar estos operadores por sí solos coincidiría con un volumen extremadamente alto de Posts. Por ejemplo, las siguientes reglas no son compatibles ya que contienen solo operadores que requieren conjunción:

has:media

has:links OR is:retweet

embedding_threshold:0.45

Si añadimos un operador independiente, como la frase "X data", la regla funciona correctamente:

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

El operador embedding_threshold: (usado con reglas semánticas embedding:) también requiere conjunción.

Operadores booleanos y agrupación

Combina múltiples operadores usando estas herramientas:

Operator	Description	Example
AND (espacio)	Los Posts deben coincidir con ambas condiciones	`snow day #NoSchool` coincide con Posts que tengan “snow” AND “day” AND #NoSchool
OR	Los Posts deben coincidir con cualquiera de las condiciones	`grumpy OR cat OR #meme` coincide con Posts con “grumpy” OR “cat” OR #meme
NOT (guion)	Excluye Posts que coincidan con esta condición	`cat #meme -grumpy` coincide con Posts con “cat” y #meme pero NO con “grumpy”
Agrupación (paréntesis)	Agrupa operadores	`(grumpy cat) OR (#meme has:images)` coincide con cualquiera de los grupos

Una nota sobre las negaciones

Todos los operadores pueden negarse excepto sample: y embedding:
El operador -is:nullcast siempre debe estar negado
Los operadores negados no pueden usarse solos
No niegues operadores agrupados. En lugar de skiing -(snow OR day OR noschool), usa skiing -snow -day -noschool
Escribir -embedding:"query" no es compatible

Orden de las operaciones

Al combinar AND y OR:

Los operadores conectados por lógica AND se combinan primero
Luego, se aplican los operadores conectados con lógica OR

Ejemplos:

Query	Evaluated as
`apple OR iphone ipad`	`apple OR (iphone ipad)`
`ipad iphone OR android`	`(iphone ipad) OR android`

Para eliminar la incertidumbre, usa paréntesis:

(apple OR iphone) ipad

iphone (ipad OR android)

Puntuación, diacríticos y sensibilidad a mayúsculas

Diacríticos: las reglas de filtered stream con acentos solo coinciden con Posts que también incluyan el acento. Por ejemplo, diacrítica coincide con diacrítica pero no con diacritica. Sensibilidad a mayúsculas: todos los operadores no distinguen entre mayúsculas y minúsculas. La regla cat coincide con cat, CAT y Cat.

Search Posts se comporta de forma diferenteAl construir consultas de búsqueda, las palabras clave con acentos coinciden con Posts con o sin los acentos. Por ejemplo, Diacrítica coincide tanto con Diacrítica como con Diacritica.

Coincidencia de Quote Tweet

Al usar filtered stream, los operadores coinciden tanto con el contenido del Quote Tweet como con el contenido del Post original que se citó.

Search Posts se comporta de manera diferente: solo coincide con el contenido del Quote Tweet, no con el Post original.

Especificidad y eficiencia

No se recomienda usar operadores amplios como una sola palabra clave o un hashtag: coincidirán con un volumen masivo de Posts y consumirán rápidamente tu conexión.

Consejos para crear reglas efectivas:

Empieza específico, luego amplía — crea reglas dirigidas que devuelvan resultados relevantes
Usa múltiples operadores — combina operadores para reducir resultados
Vigila tu recuento de caracteres — toda la cadena de la regla cuenta para el límite

Ejemplo de progresión:

# Demasiado amplio - más de 200,000 Posts por día
happy

# Mejor - añade filtro de idioma y exclusiones
(happy OR happiness) lang:en -birthday -is:retweet

# Aún mejor - 59 caracteres, más específico
(happy OR happiness) place_country:GB -birthday -is:retweet

Construir una regla de forma iterativa

Paso 1: comienza con una regla básica

happy OR happiness

Paso 2: prueba y reduce según los resultados

Notamos Posts en muchos idiomas. Añade un filtro de idioma:

(happy OR happiness) lang:en

Estamos obteniendo felicitaciones de cumpleaños. Exclúyelas junto con los Retweets:

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

Paso 3: amplía para una mejor cobertura

Queremos capturar más sentimiento. Añade palabras clave relacionadas:

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

Paso 4: ajusta según las tendencias

Están apareciendo Posts de vacaciones. Exclúyelos:

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

Añadir y eliminar reglas

Usa POST /2/tweets/search/stream/rules para añadir o eliminar reglas.

Añadir reglas

Envía un cuerpo JSON add con el value (la regla) y un tag opcional (para identificar los Posts coincidentes):

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"}
    ]
  }'

Eliminar reglas

Envía un cuerpo JSON delete con los IDs de las reglas a eliminar:

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"
      ]
    }
  }'

Ejemplos de reglas

Seguimiento de un desastre natural

Coincide con Posts de agencias meteorológicas sobre el huracán 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álisis de sentimiento para #nowplaying

Sentimiento 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"
}

Sentimiento 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"
}

Uso de Post annotations

Encuentra Posts en japonés sobre mascotas (no gatos) con imágenes usando el operador context:: Primero, utiliza Post lookup con tweet.fields=context_annotations para identificar los IDs de domain.entity:

Cats: 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"
}

Coincidencia semántica con embeddings (Enterprise)

Usa el operador embedding: para coincidir con Posts por significado conceptual en lugar de palabras clave. Esto requiere Enterprise + Embedding tier.

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

Combínalo con operadores estructurales para mayor precisión:

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

Consulta la referencia de operadores para todos los detalles y las mejores prácticas.

Próximos pasos

Referencia de operadores

Lista completa de operadores disponibles

Quickstart de filtered stream

Conéctate a tu stream

Código de ejemplo

Ejemplos de código en varios lenguajes

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Construir una regla

Limitaciones de las reglas

Tipos de operadores: independientes y que requieren conjunción

Operadores booleanos y agrupación

Orden de las operaciones

Puntuación, diacríticos y sensibilidad a mayúsculas

Coincidencia de Quote Tweet

Especificidad y eficiencia

Construir una regla de forma iterativa

Paso 1: comienza con una regla básica

Paso 2: prueba y reduce según los resultados

Paso 3: amplía para una mejor cobertura

Paso 4: ajusta según las tendencias

Añadir y eliminar reglas

Añadir reglas

Eliminar reglas

Ejemplos de reglas

Seguimiento de un desastre natural

Análisis de sentimiento para #nowplaying

Uso de Post annotations

Coincidencia semántica con embeddings (Enterprise)

Próximos pasos

Referencia de operadores

Quickstart de filtered stream

Código de ejemplo

​Limitaciones de las reglas

​Tipos de operadores: independientes y que requieren conjunción

​Operadores booleanos y agrupación

​Orden de las operaciones

​Puntuación, diacríticos y sensibilidad a mayúsculas

​Coincidencia de Quote Tweet

​Especificidad y eficiencia

​Construir una regla de forma iterativa

​Paso 1: comienza con una regla básica

​Paso 2: prueba y reduce según los resultados

​Paso 3: amplía para una mejor cobertura

​Paso 4: ajusta según las tendencias

​Añadir y eliminar reglas

​Añadir reglas

​Eliminar reglas

​Ejemplos de reglas

​Seguimiento de un desastre natural

​Análisis de sentimiento para #nowplaying

​Uso de Post annotations

​Coincidencia semántica con embeddings (Enterprise)

​Próximos pasos

Referencia de operadores

Quickstart de filtered stream

Código de ejemplo

Limitaciones de las reglas

Tipos de operadores: independientes y que requieren conjunción

Operadores booleanos y agrupación

Orden de las operaciones

Puntuación, diacríticos y sensibilidad a mayúsculas

Coincidencia de Quote Tweet

Especificidad y eficiencia

Construir una regla de forma iterativa

Paso 1: comienza con una regla básica

Paso 2: prueba y reduce según los resultados

Paso 3: amplía para una mejor cobertura

Paso 4: ajusta según las tendencias

Añadir y eliminar reglas

Añadir reglas

Eliminar reglas

Ejemplos de reglas

Seguimiento de un desastre natural

Análisis de sentimiento para #nowplaying

Uso de Post annotations

Coincidencia semántica con embeddings (Enterprise)

Próximos pasos