> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-d5730eee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtered Stream Operators

> Complete Enterprise Filtered Stream operator reference, including keyword, has:, is:, and semantic embedding: operators for matching Posts in real time.

This page provides a complete list of operators available when [building rules](/x-api/posts/filtered-stream/integrate/build-a-rule) for Filtered Stream.

## Overview

Operators are used to match on specific Post attributes. There are two types:

* **Standalone operators** — Can be used alone or with any other operators
* **Conjunction-required operators** — Must be used with at least one standalone operator

Some advanced operators (such as semantic embedding) require Embedding tier access in addition to Enterprise.

***

## Keyword and phrase operators

| Operator                | Type       | Summary                                                            | Example                               |
| :---------------------- | :--------- | :----------------------------------------------------------------- | :------------------------------------ |
| `keyword`               | Standalone | Matches a keyword within the Post body (tokenized match)           | `pepsi OR cola OR "coca cola"`        |
| `emoji`                 | Standalone | Matches an emoji within the Post body                              | `(😃 OR 😡) 😬`                       |
| `"exact phrase"`        | Standalone | Matches the exact phrase within the Post body                      | `("X API" OR #v2) -"filtered stream"` |
| `"keyword1 keyword2"~N` | Standalone | Proximity match — keywords within N tokens of each other (max N=6) | `"social media"~5`                    |

***

## Entity operators

| Operator | Type       | Summary                                          | Example                      |
| :------- | :--------- | :----------------------------------------------- | :--------------------------- |
| `#`      | Standalone | Matches Posts containing a hashtag (exact match) | `#thankunext #fanart`        |
| `@`      | Standalone | Matches Posts mentioning a username              | `(@XDevelopers OR @api) -@x` |
| `$`      | Standalone | Matches Posts containing a cashtag               | `$twtr OR @XDevelopers -$fb` |

***

## User operators

| Operator       | Type       | Summary                                   | Example                        |
| :------------- | :--------- | :---------------------------------------- | :----------------------------- |
| `from:`        | Standalone | Matches Posts from a specific user        | `from:XDevelopers OR from:api` |
| `to:`          | Standalone | Matches Posts in reply to a specific user | `to:XDevelopers OR to:api`     |
| `retweets_of:` | Standalone | Matches Retweets of a specific user       | `retweets_of:XDevelopers`      |

***

## URL operators

| Operator           | Type       | Summary                                                         | Example                         |
| :----------------- | :--------- | :-------------------------------------------------------------- | :------------------------------ |
| `url:`             | Standalone | Tokenized match on URL (matches `url` or `expanded_url` fields) | `url:"https://developer.x.com"` |
| `url_title:`       | —          | Keyword match on expanded URL HTML title metadata               | `url_title:snow`                |
| `url_description:` | —          | Keyword match on expanded page description metadata             | `url_description:weather`       |
| `url_contains:`    | —          | Literal match on URL content                                    | `url_contains:photos`           |

***

## Context and entity operators

| Operator           | Type       | Summary                                           | Example                                           |
| :----------------- | :--------- | :------------------------------------------------ | :------------------------------------------------ |
| `context:`         | Standalone | Matches Posts with a specific domain/entity pair  | `context:10.799022225751871488` or `context:47.*` |
| `entity:`          | Standalone | Matches Posts with a specific entity string value | `entity:"Michael Jordan"`                         |
| `conversation_id:` | Standalone | Matches Posts in a conversation thread            | `conversation_id:1334987486343299072`             |

***

## User profile operators

| Operator        | Type       | Summary                                   | Example                                        |
| :-------------- | :--------- | :---------------------------------------- | :--------------------------------------------- |
| `bio:`          | Standalone | Matches keyword in Post author's bio      | `bio:developer OR bio:"data engineer"`         |
| `bio_name:`     | Standalone | Matches keyword in Post author's name     | `bio_name:phd OR bio_name:md`                  |
| `bio_location:` | Standalone | Matches keyword in Post author's location | `bio_location:"big apple" OR bio_location:nyc` |

***

## Location operators

| Operator         | Type       | Summary                                  | Example                                                     |
| :--------------- | :--------- | :--------------------------------------- | :---------------------------------------------------------- |
| `place:`         | Standalone | Matches Posts tagged with a location     | `place:"new york city" OR place:seattle`                    |
| `place_country:` | Standalone | Matches Posts with a country code        | `place_country:US OR place_country:MX`                      |
| `point_radius:`  | Standalone | Matches Posts within a radius of a point | `point_radius:[2.355128 48.861118 16km]`                    |
| `bounding_box:`  | Standalone | Matches Posts within a bounding box      | `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` |

***

## Post type operators

| Operator       | Type                 | Summary                                      | Example                         |
| :------------- | :------------------- | :------------------------------------------- | :------------------------------ |
| `is:retweet`   | Conjunction required | Matches Retweets                             | `data @XDevelopers -is:retweet` |
| `is:reply`     | Conjunction required | Matches replies                              | `from:XDevelopers is:reply`     |
| `is:quote`     | Conjunction required | Matches Quote Tweets                         | `"sentiment analysis" is:quote` |
| `is:verified`  | Conjunction required | Matches Posts from verified authors          | `#nowplaying is:verified`       |
| `-is:nullcast` | Conjunction required | Excludes promotional Posts (must be negated) | `"mobile games" -is:nullcast`   |

***

## Content type operators

| Operator         | Type                 | Summary                                      | Example                              |
| :--------------- | :------------------- | :------------------------------------------- | :----------------------------------- |
| `has:hashtags`   | Conjunction required | Matches Posts with hashtags                  | `from:XDevelopers -has:hashtags`     |
| `has:cashtags`   | Conjunction required | Matches Posts with cashtags                  | `#stonks has:cashtags`               |
| `has:links`      | Conjunction required | Matches Posts with links                     | `from:XDevelopers has:links`         |
| `has:mentions`   | Conjunction required | Matches Posts with mentions                  | `#nowplaying has:mentions`           |
| `has:media`      | Conjunction required | Matches Posts with media (photo, GIF, video) | `(kittens OR puppies) has:media`     |
| `has:images`     | Conjunction required | Matches Posts with images                    | `#meme has:images`                   |
| `has:video_link` | Conjunction required | Matches Posts with native X videos           | `#icebucketchallenge has:video_link` |
| `has:geo`        | Conjunction required | Matches Posts with geolocation data          | `recommend #paris has:geo`           |

***

## Sampling and language operators

| Operator  | Type                 | Summary                                         | Example                          |
| :-------- | :------------------- | :---------------------------------------------- | :------------------------------- |
| `sample:` | Conjunction required | Returns a random percent sample (1-100)         | `#nowplaying @spotify sample:15` |
| `lang:`   | Conjunction required | Matches Posts classified as a specific language | `recommend #paris lang:en`       |

***

## User metrics operators

| Operator           | Type | Summary                                                | Example                       |
| :----------------- | :--- | :----------------------------------------------------- | :---------------------------- |
| `followers_count:` | —    | Matches Posts from users with follower count in range  | `followers_count:1000..10000` |
| `tweets_count:`    | —    | Matches Posts from users with Post count in range      | `tweets_count:1000..10000`    |
| `following_count:` | —    | Matches Posts from users with following count in range | `following_count:1000..10000` |
| `listed_count:`    | —    | Matches Posts from users in specified number of Lists  | `listed_count:10..100`        |

***

## Post reference operators

| Operator                | Type | Summary                                          | Example                                    |
| :---------------------- | :--- | :----------------------------------------------- | :----------------------------------------- |
| `in_reply_to_tweet_id:` | —    | Matches replies to a specific Post               | `in_reply_to_tweet_id:1539382664746020864` |
| `retweets_of_tweet_id:` | —    | Matches Retweets of a specific Post              | `retweets_of_tweet_id:1539382664746020864` |
| `source:`               | —    | Matches Posts from a specific source application | `source:"X for iPhone"`                    |

***

## Logical operators

| Operator    | Summary                          | Example                    |
| :---------- | :------------------------------- | :------------------------- |
| `OR`        | Logical OR between expressions   | `cat OR dog`               |
| Space (AND) | Logical AND between expressions  | `cat dog` (both required)  |
| `()`        | Grouping for complex expressions | `(cat OR dog) -is:retweet` |
| `-`         | Negation/exclusion               | `cat -grumpy`              |

***

## Semantic operators

<Note>
  **Requires Embedding tier**

  The `embedding:` and `embedding_threshold:` operators require Embedding tier access on your Enterprise Filtered Stream instance. If not provisioned, rule creation will fail with an "'embedding' is not an available operator" error.
</Note>

These operators use a neural embedding model to match Posts by *semantic similarity* to a query, rather than requiring exact keyword matches.

| Operator                   | Type                 | Summary                                                                                         | Example                                                          |
| :------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `embedding:"query"`        | Standalone           | Matches Posts semantically similar to the query. Multi-word queries must be quoted.             | `embedding:"climate change policy"`                              |
| `embedding_threshold:X.XX` | Conjunction required | Minimum cosine similarity for a match (0.0–1.0). Defaults to `0.3`. Use values between 0.3–0.6. | `embedding:"cryptocurrency regulation" embedding_threshold:0.45` |

### Key requirements and notes

* `embedding_threshold:` **cannot** be the only operator in a rule. Pair it with `embedding:` (or another standalone operator).
* **Do not negate** `embedding:` (e.g. `-embedding:"..."` is unsupported).
* Longer, descriptive natural language queries produce better results than short keywords.
* Embedding query processing is asynchronous — newly created rules may take a few seconds before they begin matching.
* When a Post matches via an embedding rule, the delivered payload's `matching_rules` entries will contain `embedding_similarity` and `embedding_threshold` (see [Matching Posts to Rules](/x-api/posts/filtered-stream/integrate/matching-returned-tweets)).

**Example rules:**

* `embedding:"electric vehicle announcements" lang:en -is:retweet has:links`
* `embedding:"natural disaster relief" embedding_threshold:0.45 has:media`
* `embedding:"renewable energy" embedding_threshold:0.4 OR embedding:"solar power investment"`

***

## Supported languages

The `lang:` operator supports these BCP 47 language codes:

| Language  | Code | Language   | Code | Language            | Code    |
| :-------- | :--- | :--------- | :--- | :------------------ | :------ |
| Amharic   | `am` | Greek      | `el` | Portuguese          | `pt`    |
| Arabic    | `ar` | Gujarati   | `gu` | Romanian            | `ro`    |
| Armenian  | `hy` | Hebrew     | `iw` | Russian             | `ru`    |
| Basque    | `eu` | Hindi      | `hi` | Serbian             | `sr`    |
| Bengali   | `bn` | Hungarian  | `hu` | Simplified Chinese  | `zh-CN` |
| Bulgarian | `bg` | Indonesian | `in` | Slovak              | `sk`    |
| Catalan   | `ca` | Italian    | `it` | Slovenian           | `sl`    |
| Croatian  | `hr` | Japanese   | `ja` | Spanish             | `es`    |
| Czech     | `cs` | Kannada    | `kn` | Swedish             | `sv`    |
| Danish    | `da` | Korean     | `ko` | Tamil               | `ta`    |
| Dutch     | `nl` | Latvian    | `lv` | Telugu              | `te`    |
| English   | `en` | Lithuanian | `lt` | Thai                | `th`    |
| Estonian  | `et` | Malayalam  | `ml` | Traditional Chinese | `zh-TW` |
| Finnish   | `fi` | Marathi    | `mr` | Turkish             | `tr`    |
| French    | `fr` | Norwegian  | `no` | Ukrainian           | `uk`    |
| German    | `de` | Persian    | `fa` | Urdu                | `ur`    |
| Georgian  | `ka` | Polish     | `pl` | Vietnamese          | `vi`    |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Build a rule" icon="filter" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
    Learn rule syntax and best practices
  </Card>

  <Card title="Filtered Stream introduction" icon="bolt" href="/x-api/posts/filtered-stream/introduction">
    Get started with Filtered Stream
  </Card>

  <Card title="Handling disconnections" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    Handle streaming disconnections
  </Card>
</CardGroup>