Crear una regla

Los endpoints de flujo filtrado devuelven Publicaciones que cumplen un conjunto de reglas aplicadas al flujo. Las reglas se componen de operadores que se aplican a una variedad de atributos de la Publicación. Se pueden aplicar varias reglas mediante el endpoint POST /tweets/search/stream/rules. Una vez que hayas agregado reglas y te hayas conectado mediante GET /tweets/search/stream, solo se devolverán las Publicaciones que coincidan con tus reglas. No necesitas cerrar la conexión para agregar o eliminar reglas.

Limitaciones de las reglas

Los límites en el número de reglas dependen de tu nivel de acceso. Consulta la introducción al flujo filtrado para conocer los límites específicos.

Tipos de operadores: independientes y que requieren conjunción

Los operadores independientes se pueden usar 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 se pueden usar por sí solos en una regla; solo se pueden usar cuando se incluye al menos un operador independiente. Esto se debe a que usar estos operadores solos haría coincidir un volumen extremadamente alto de Publicaciones. Por ejemplo, las siguientes reglas no se admiten ya que contienen únicamente operadores que requieren conjunción:

has:media

has:links OR is:retweet

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

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

Operadores booleanos y agrupación

Encadena varios operadores utilizando estas herramientas:

Operador	Descripción	Ejemplo
AND (espacio)	Las Publicaciones deben coincidir con ambas condiciones	`snow day #NoSchool` coincide con Publicaciones que contienen “snow”, “day” y #NoSchool
OR	Las Publicaciones deben coincidir con cualquiera de las condiciones	`grumpy OR cat OR #meme` coincide con Publicaciones que contienen “grumpy”, “cat” o #meme
NOT (guion)	Excluye las Publicaciones que coinciden con esta condición	`cat #meme -grumpy` coincide con Publicaciones que contienen “cat” y #meme pero no “grumpy”
Grouping (paréntesis)	Agrupa operadores	`(grumpy cat) OR (#meme has:images)` coincide con cualquiera de los grupos

Una nota sobre negaciones

Todos los operadores se pueden negar excepto sample:
El operador -is:nullcast siempre debe usarse en forma negada
Los operadores negados no se pueden usar por sí solos
No niegues los operadores agrupados. En lugar de skiing -(snow OR day OR noschool), usa skiing -snow -day -noschool

Orden de operaciones

Al combinar AND y OR:

Primero se combinan los operadores conectados por lógica AND
Luego se aplican los operadores conectados con lógica OR

Ejemplos:

Query	Se evalúa como
`apple OR iphone ipad`	`apple OR (iphone ipad)`
`ipad iphone OR android`	`(iphone ipad) OR android`

Para evitar ambigüedades, usa paréntesis:

(apple OR iphone) ipad

iphone (ipad OR android)

Signos de puntuación, diacríticos y distinción entre mayúsculas y minúsculas

Diacríticos: Las reglas del flujo filtrado con acentos solo coinciden con Publicaciones que también incluyen el acento. Por ejemplo, diacrítica coincide con diacrítica pero no con diacritica. Distinción entre mayúsculas y minúsculas: Ningún operador distingue entre mayúsculas y minúsculas. La regla cat coincide con cat, CAT y Cat.

La búsqueda de Publicaciones se comporta de forma diferenteAl crear consultas de búsqueda, las palabras clave con acentos coinciden con Publicaciones tanto con como sin acentos. Por ejemplo, Diacrítica coincide tanto con Diacrítica como con Diacritica.

Coincidencia de Tweets citados

Cuando se usa el flujo filtrado, los operadores se evalúan tanto sobre el contenido del Tweet citado como sobre el contenido de la Publicación original que fue citada.

Buscar Publicaciones se comporta de manera diferente: solo se evalúa sobre el contenido del Tweet citado, no sobre la Publicación original.

Especificidad y eficiencia

No se recomienda usar operadores generales como una sola palabra clave o un hashtag: harán coincidir un volumen masivo de Publicaciones y agotarán rápidamente tu conexión.

Consejos para crear reglas efectivas:

Empieza de forma específica y luego amplía — Crea reglas dirigidas que devuelvan resultados relevantes
Usa múltiples operadores — Combina operadores para acotar los resultados
Controla el número de caracteres — Toda la cadena de la regla cuenta para el límite

Ejemplo de progresión:

# Too broad - 200,000+ Posts per day
happy

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

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet

Crear una regla de forma iterativa

Paso 1: Empieza con una regla básica

happy OR happiness

Paso 2: Prueba y acota según los resultados

Observamos Publicaciones en muchos idiomas. Añade un filtro de idioma:

(happy OR happiness) lang:en

Estamos recibiendo mensajes de felicitación de cumpleaños. Excluye esos y los Retweets:

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

Paso 3: Ampliar para mejorar la cobertura

Queremos captar más señales de sentimiento. Añade palabras clave relacionadas:

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

Paso 4: Ajustar según las tendencias

Están empezando a aparecer Publicaciones sobre festividades. Exclúyelas:

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

Añadir y eliminar reglas

Utiliza POST /2/tweets/search/stream/rules para agregar o eliminar reglas.

Agregar reglas

Envía un cuerpo JSON add con el campo value (la regla) y un campo tag opcional (para identificar las Publicaciones que coincidan):

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

Eliminación de reglas

Envía un cuerpo JSON delete con los identificadores de las reglas que deseas 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

Detecta Publicaciones 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 sentimientos 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 anotaciones de Publicaciones

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

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

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

Próximos pasos

Referencia de operadores

Lista completa de operadores disponibles

Inicio rápido del flujo filtrado

Conecta tu flujo

Código de ejemplo

Ejemplos de código en varios lenguajes