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

# Filtered Stream Operators

> Complete X API v2 Filtered Stream operator reference, covering keyword, has:, is:, and Enterprise-only semantic embedding: operators for stream rules.

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

Most operators are available on both Pay-per-use and Enterprise. Some advanced operators (such as semantic embedding) require Enterprise with additional tier access.

***

## 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`       |
| `from_affiliate_of:` | Standalone | Matches Posts from affiliates of a specific user        | `from_affiliate_of:XDevelopers` |
| `to_affiliate_of:`   | Standalone | Matches Posts in reply to affiliates of a specific user | `to_affiliate_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                       |
| :----------------- | :--- | :----------------------------------------------------------------------- | :---------------------------- |
| `min_followers:`   | —    | Matches Posts from users with at least the specified number of followers | `min_followers:1000`          |
| `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>
  **Enterprise only — Embedding tier required**

  The `embedding:` and `embedding_threshold:` operators are only available on Enterprise accounts provisioned with Embedding tier access for Filtered Stream. On unsupported tiers, rule creation will be rejected with an "unavailable operator" error. Contact your account representative to enable.
</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>