From 8a273e74bd64819a86177418a3bd372012332b50 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Fri, 7 Nov 2025 12:03:53 -0800 Subject: [PATCH 1/2] Add new search operators --- docs.json | 2 + .../integrate/build-a-rule.mdx | 56 +----------------- .../filtered-stream/integrate/operators.mdx | 59 +++++++++++++++++++ .../posts/search/integrate/build-a-query.mdx | 47 +-------------- x-api/posts/search/integrate/operators.mdx | 51 ++++++++++++++++ 5 files changed, 115 insertions(+), 100 deletions(-) create mode 100644 x-api/posts/filtered-stream/integrate/operators.mdx create mode 100644 x-api/posts/search/integrate/operators.mdx diff --git a/docs.json b/docs.json index a0c5d230..b49e8ee1 100644 --- a/docs.json +++ b/docs.json @@ -176,6 +176,7 @@ "pages": [ "x-api/posts/search/integrate/overview", "x-api/posts/search/integrate/build-a-query", + "x-api/posts/search/integrate/operators", "x-api/posts/search/integrate/paginate" ] } @@ -224,6 +225,7 @@ "group": "Integration guide", "pages": [ "x-api/posts/filtered-stream/integrate/build-a-rule", + "x-api/posts/filtered-stream/integrate/operators", "x-api/posts/filtered-stream/integrate/consuming-streaming-data", "x-api/posts/filtered-stream/integrate/handling-disconnections", "x-api/posts/filtered-stream/integrate/handling-high-volume-capacity", diff --git a/x-api/posts/filtered-stream/integrate/build-a-rule.mdx b/x-api/posts/filtered-stream/integrate/build-a-rule.mdx index 0b2e7d10..09bbb862 100644 --- a/x-api/posts/filtered-stream/integrate/build-a-rule.mdx +++ b/x-api/posts/filtered-stream/integrate/build-a-rule.mdx @@ -22,7 +22,6 @@ Multiple rules can be applied to a stream using the [POST /tweets/search/stream/ * [Iteratively building a rule](#iteratively-building-a-rule) * [Adding and removing rules](#adding-and-removing-rules) * [Rule examples](#rule-examples) -* [List of operators](#operators) ### Building a rule @@ -252,57 +251,4 @@ Here is what the rule would look like: "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja", "tag": "Japanese pets with images - no cats" } -``` - -### Operators - -**Note:** For some operators, an alternate name, or alias, is available. - -| **Operator** | **Type** | **Description** | -|:------------------------------|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `keyword` | Standalone | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters.
For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes.

Example: `pepsi OR cola OR "coca cola"` | -| `emoji` | Standalone | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body.

Note that if an emoji has a variant, you must wrap it in double quotes to add to a rule.

Example: `(😃 OR 😡) 😬` | -| `"exact phrase match"` | Standalone | Matches the exact phrase within the body of a Post.

Example: `("X API" OR #v2) -"filtered stream"` | -| `"keyword1 keyword2"~N` | Standalone | Proximity operator that matches a Post where keywords are within `N` tokens of each other.
Keywords in reverse order can be no more than `N-2` tokens apart. `N` cannot be greater than `6`.

Example: `"social media"~5 OR "API"~3` | -| `#` | Standalone | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post.

This operator performs an exact match, NOT a tokenized match, meaning the rule `#thanku` will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext.

Example: `#thankunext #fanart OR @arianagrande` | -| `@` | Standalone | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character).

Example: `(@XDevelopers OR @api) -@x` | -| `$` | Standalone | Matches any Post that contains the specified 'cashtag' (where the leading character of the token is the $ character).

Note that the cashtag operator relies on X's 'symbols' entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself.

Example: `$twtr OR @XDevelopers -$fb` | -| `from:` | Standalone | Matches any Post from a specific user.
The value can be either the username (excluding the @ character) or the user's numeric user ID.

You can only pass a single username/ID `from:` operator.

Example: `from:XDevelopers OR from:api -from:X` | -| `to:` | Standalone | Matches any Post that is in reply to a particular user.
The value can be either the username (excluding the @ character) or the user's numeric user ID.

You can only pass a single username/ID per `to:` operator.

Example: `to:XDevelopers OR to:api -to:x` | -| `url:` | Standalone | Performs a tokenized match on any validly-formatted URL of a Post.

This operator can match on the contents of both the `url` or `expanded_url` fields. For example, a Post containing "You should check out X Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.x.com) will match both the following rules:

`from:XDevelopers url:"https://developer.x.com"`
(because it will match the contents of `entities.urls.expanded_url`)

`from:XDevelopers url:"https://t.co"`
(because it will match the contents of `entities.urls.url`)

Tokens and phrases containing punctuation or special characters should be double-quoted (for example, `url:"/developer"`). Similarly, to match on a specific protocol, enclose in double-quotes (for example, `url:"https://developer.x.com"`).

You can only pass a single URL per `url:` operator. | -| `retweets_of:` | Standalone | *Available alias:* `retweets_of_user:`
Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user's numeric user ID.

You can only pass a single username/ID per `retweets_of:` operator.

Example: `retweets_of:XDevelopers OR retweets_of:twitterapi`
See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs. | -| `context:` | Standalone | Matches Posts with a specific domain id and/or domain id, entity id pair where * represents a wildcard. To learn more about this operator, please visit our page on [Post annotations](/x-api/fundamentals/post-annotations).

You can only pass a single domain/entity per `context:` operator.

`context:domain_id.entity_id`
`context:domain_id.*`
`context:*.entity_id`

Examples:
`context:10.799022225751871488`
(`domain_id.entity_id` returns Posts matching that specific domain-entity pair)

`context:47.*`
(`domain_id.*` returns Posts matching that domain ID, with any domain-entity pair)

`context:*.799022225751871488`
(`*.entity_id` returns Posts matching that entity ID, with any domain-entity pair) | -| `entity:` | Standalone | Matches Posts with a specific entity string value. To learn more about this operator, please visit our page on [annotations](/x-api/fundamentals/post-annotations).

You can only pass a single entity per `entity:` operator.

`entity:"string declaration of entity/place"`

Examples: `entity:"Michael Jordan" OR entity:"Barcelona"` | -| `conversation_id:` | Standalone | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the `conversation_id` is added to its JSON payload.

You can only pass a single conversation ID per `conversation_id:` operator.

Example: `conversation_id:1334987486343299072 (from:XDevelopers OR from:api)` | -| `bio:` | Standalone | *Available alias:* `user_bio:`
Matches a keyword or phrase within the Post publisher's bio. This is a tokenized match within the contents of the `description` field within the [User object](/x-api/fundamentals/data-dictionary#user).

Example: `bio:developer OR bio:"data engineer" OR bio:academic` | -| `bio_name:` | Standalone | Matches a keyword within the Post publisher's user bio name. This is a tokenized match within the contents of a user's "name" field within the [User object](/x-api/fundamentals/data-dictionary#user).

Example: `bio_name:phd OR bio_name:md` | -| `bio_location:` | Standalone | *Available alias:* `user_bio_location:`
Matches Posts that are published by users whose location contains the specified keyword or phrase. This operator performs a tokenized match, similar to the normal keyword rules on the message body.

This location is part of the [User object](/x-api/fundamentals/data-dictionary#user), matches on the 'location' field, and is a non-normalized, user-generated, free-form string. It is also different from a Post's location (see `place:`).

Example: `bio_location:"big apple" OR bio_location:nyc OR bio_location:manhattan` | -| `place:` | Standalone | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

You can only pass a single place per `place:` operator.

Note: See the [GET geo/search](https://developer.x.com/content/developer-twitter/en/docs/geo/places-near-location/api-reference/get-geo-search) standard v1.1 endpoint for how to obtain X place IDs.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | -| `place_country:` | Standalone | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.

You can find a list of valid ISO codes on [Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

You can only pass a single ISO code per `place_country:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place_country:US OR place_country:MX OR place_country:CA` | -| `point_radius:` | Standalone | Matches against the `place.geo.coordinates` object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region.

`point_radius:[longitude latitude radius]`

- Units of radius supported are miles (mi) and kilometers (km)
- Radius must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees
- Rule arguments are contained within brackets, space delimited

You can only pass a single geo polygon per `point_radius:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | -| `bounding_box:` | Standalone | *Available alias:* `geo_bounding_box:`
Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region.

`bounding_box:[west_long south_lat east_long north_lat]`

- `west_long south_lat` represent the southwest corner of the bounding box where `west_long` is the longitude of that point, and `south_lat` is the latitude.
- `east_long north_lat` represent the northeast corner of the bounding box, where `east_long` is the longitude of that point, and `north_lat` is the latitude.
- Width and height of the bounding box must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees.
- Rule arguments are contained within brackets, space delimited.

You can only pass a single geo polygon per `bounding_box:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | -| `is:retweet` | Conjunction required | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator.

Example: `data @XDevelopers -is:retweet` | -| `is:reply` | Conjunction required | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a rule from delivery.

When used with the filtered stream, this operator matches on replies to an original Post, replies in quoted Posts, and replies in Retweets.

Example: `from:XDevelopers is:reply` | -| `is:quote` | Conjunction required | Returns all Quote Tweets, also known as Posts with comments.

Example: `"sentiment analysis" is:quote` | -| `is:verified` | Conjunction required | Deliver only Posts whose authors are verified by X.

Example: `#nowplaying is:verified` | -| `-is:nullcast` | Conjunction required | Removes Posts created for promotion only on ads.twitter.com that have a `source:"Twitter for Advertisers (legacy)"` or `source:"Twitter for Advertisers".`
This operator must be negated.

For more info on Nullcasted Posts, see our page on [Post availability](https://developer.x.com/content/developer-twitter/en/docs/twitter-api/v1/tweets/post-and-engage/guides/tweet-availability).

Example: `"mobile games" -is:nullcast` | -| `has:hashtags` | Conjunction required | Matches Posts that contain at least one hashtag.

Example: `from:XDevelopers -has:hashtags` | -| `has:cashtags` | Conjunction required | Matches Posts that contain a cashtag symbol (with a leading '$' character. For example, `$tag`).

Example: `#stonks has:cashtags` | -| `has:links` | Conjunction required | This operator matches Posts which contain links and media in the Post body.

Example: `from:XDevelopers announcement has:links` | -| `has:mentions` | Conjunction required | Matches Posts that mention another X user.

Example: `#nowplaying has:mentions` | -| `has:media` | Conjunction required | *Available alias:* `has:media_link`
Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites.

Example: `(kittens OR puppies) has:media` | -| `has:images` | Conjunction required | Matches Posts that contain a recognized URL to an image.

Example: `#meme has:images` | -| `has:video_link` | Conjunction required | *Available alias:* `has:videos`
Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites.

Example: `#icebucketchallenge has:video_link` | -| `has:geo` | Conjunction required | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate.

Note: Operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data.

Example: `recommend #paris has:geo -bakery` | -| `sample:` | Conjunction required | Returns a random percent sample of Posts that match a rule rather than the entire set of Posts. The percent value must be represented by an integer between 1 and 100 (for example, `sample:10` will return a random 10% sample).

This operator first reduces the scope of the stream to the percentage you specified, then the rule/filter is applied to that sampled subset. In other words, if you are using, for example, `sample:10`, each Post will have a 10% chance of being in the sample.

This operator applies to the entire rule and requires all OR'd terms to be grouped.

Example: `#nowplaying @spotify sample:15` | -| `lang:` | Conjunction required | Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

You can only pass a single BCP 47 language identifier per `lang:` operator.

Note: if no language classification can be made the provided result is 'und' (for undefined).

Example: `recommend #paris lang:en`

The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

| Language | BCP 47 |
|-|-|
| Amharic | `am` |
| Arabic | `ar` |
| Armenian | `hy` |
| Basque | `eu` |
| Bengali | `bn` |
| Bosnian | `bs` |
| Bulgarian | `bg` |
| Burmese | `my` |
| Croatian | `hr` |
| Catalan | `ca` |
| Czech | `cs` |
| Danish | `da` |
| Dutch | `nl` |
| English | `en` |
| Estonian | `et` |
| Finnish | `fi` |
| French | `fr` |
| Georgian | `ka` |
| German | `de` |
| Greek | `el` |
| Gujarati | `gu` |
| Haitian Creole | `ht` |
| Hebrew | `iw` |
| Hindi | `hi` |
| Latinized Hindi | `hi-Latn` |
| Hungarian | `hu` |
| Icelandic | `is` |
| Indonesian | `in` |
| Italian | `it` |
| Japanese | `ja` |
| Kannada | `kn` |
| Khmer | `km` |
| Korean | `ko` |
| Lao | `lo` |
| Latvian | `lv` |
| Lithuanian | `lt` |
| Malayalam | `ml` |
| Maldivian | `dv` |
| Marathi | `mr` |
| Nepali | `ne` |
| Norwegian | `no` |
| Oriya | `or` |
| Panjabi | `pa` |
| Pashto | `ps` |
| Persian | `fa` |
| Polish | `pl` |
| Portuguese | `pt` |
| Romanian | `ro` |
| Russian | `ru` |
| Serbian | `sr` |
| Simplified Chinese | `zh-CN` |
| Sindhi | `sd` |
| Sinhala | `si` |
| Slovak | `sk` |
| Slovenian | `sl` |
| Sorani Kurdish | `ckb` |
| Spanish | `es` |
| Swedish | `sv` |
| Tagalog | `tl` |
| Tamil | `ta` |
| Telugu | `te` |
| Thai | `th` |
| Tibetan | `bo` |
| Traditional Chinese | `zh-TW` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Urdu | `ur` |
| Uyghur | `ug` |
| Vietnamese | `vi` |
| Welsh | `cy` | | -| `followers_count:` | | Matches Posts when the author has a followers count within the given range.
If a single number is specified, any number equal to or higher will match.

Example: `followers_count:500`

Additionally, a range can be specified to match any number in the given range.

Example: `followers_count:1000..10000` | -| `tweets_count:` | | *Available alias:* `statuses_count:`
Matches Posts when the author has posted a number of Posts that falls within the given range.
If a single number is specified, any number equal to or higher will match.

Example: `tweets_count:1000`

Additionally, a range can be specified to match any number in the given range.

Example: `tweets_count:1000..10000` | -| `following_count:` | | *Available alias:* `friends_count:`
Matches Posts when the author has a friends count (the number of users they follow) that falls within the given range.
If a single number is specified, any number equal to or higher will match.

Example: `following_count:500`

Additionally, a range can be specified to match any number in the given range.

Example: `following_count:1000..10000` | -| `listed_count:` | | *Available alias:* `user_in_lists_count:`
Matches Posts when the author is included in the specified number of Lists.
If a single number is specified, any number equal to or higher will match.

Example: `listed_count:10`

Additionally, a range can be specified to match any number in the given range.

Example: `listed_count:10..100` | -| `url_title:` | | *Available alias:* `within_url_title:`
Performs a keyword/phrase match on the expanded URL HTML title metadata.

Example: `url_title:snow` | -| `url_description:` | | *Available alias:* `within_url_description:`
Performs a keyword/phrase match on the expanded page description metadata.

Example: `url_description:weather` | -| `url_contains:` | | Matches Posts with URLs that literally contain the given phrase or keyword. To search for patterns with punctuation in them (i.e., google.com) enclose the search term in quotes.
NOTE: This will match against the expanded URL as well.

Example: `url_contains:photos` | -| `source:` | | Matches any Post generated by the given source application. The value must be either the name of the application or the application's URL. Cannot be used alone.

Example: `source:"X for iPhone"`

Note: As an X app developer, Posts created programmatically by your application will have the source of your application Name and Website URL set in your [app settings](/resources/fundamentals/developer-apps#app-management). | -| `in_reply_to_tweet_id:` | | *Available alias:* `in_reply_to_status_id:`
Deliver only explicit Replies to the specified Post.

Example: `in_reply_to_tweet_id:1539382664746020864` | -| `retweets_of_tweet_id:` | | *Available alias:* `retweets_of_status_id:`
Deliver only explicit (or native) Retweets of the specified Post. Note that the status ID used should be the ID of an original Post and not a Retweet.

Example: `retweets_of_tweet_id:1539382664746020864` | \ No newline at end of file +``` \ No newline at end of file diff --git a/x-api/posts/filtered-stream/integrate/operators.mdx b/x-api/posts/filtered-stream/integrate/operators.mdx new file mode 100644 index 00000000..8a0a3120 --- /dev/null +++ b/x-api/posts/filtered-stream/integrate/operators.mdx @@ -0,0 +1,59 @@ +--- +title: Stream Rule Operators +sidebarTitle: Operators +--- + +This page provides a list of operators availble when [building rules](/x-api/posts/search/integrate/build-a-query) for Filtered Stream v2. + +## List of operators + +**Note:** For some operators, an alternate name, or alias, is available. + +| **Operator** | **Type** | **Description** | +|:------------------------------|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `keyword` | Standalone | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters.
For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes.

Example: `pepsi OR cola OR "coca cola"` | +| `emoji` | Standalone | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body.

Note that if an emoji has a variant, you must wrap it in double quotes to add to a rule.

Example: `(😃 OR 😡) 😬` | +| `"exact phrase match"` | Standalone | Matches the exact phrase within the body of a Post.

Example: `("X API" OR #v2) -"filtered stream"` | +| `"keyword1 keyword2"~N` | Standalone | Proximity operator that matches a Post where keywords are within `N` tokens of each other.
Keywords in reverse order can be no more than `N-2` tokens apart. `N` cannot be greater than `6`.

Example: `"social media"~5 OR "API"~3` | +| `#` | Standalone | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post.

This operator performs an exact match, NOT a tokenized match, meaning the rule `#thanku` will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext.

Example: `#thankunext #fanart OR @arianagrande` | +| `@` | Standalone | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character).

Example: `(@XDevelopers OR @api) -@x` | +| `$` | Standalone | Matches any Post that contains the specified 'cashtag' (where the leading character of the token is the $ character).

Note that the cashtag operator relies on X's 'symbols' entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself.

Example: `$twtr OR @XDevelopers -$fb` | +| `from:` | Standalone | Matches any Post from a specific user.
The value can be either the username (excluding the @ character) or the user's numeric user ID.

You can only pass a single username/ID `from:` operator.

Example: `from:XDevelopers OR from:api -from:X` | +| `to:` | Standalone | Matches any Post that is in reply to a particular user.
The value can be either the username (excluding the @ character) or the user's numeric user ID.

You can only pass a single username/ID per `to:` operator.

Example: `to:XDevelopers OR to:api -to:x` | +| `url:` | Standalone | Performs a tokenized match on any validly-formatted URL of a Post.

This operator can match on the contents of both the `url` or `expanded_url` fields. For example, a Post containing "You should check out X Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.x.com) will match both the following rules:

`from:XDevelopers url:"https://developer.x.com"`
(because it will match the contents of `entities.urls.expanded_url`)

`from:XDevelopers url:"https://t.co"`
(because it will match the contents of `entities.urls.url`)

Tokens and phrases containing punctuation or special characters should be double-quoted (for example, `url:"/developer"`). Similarly, to match on a specific protocol, enclose in double-quotes (for example, `url:"https://developer.x.com"`).

You can only pass a single URL per `url:` operator. | +| `retweets_of:` | Standalone | *Available alias:* `retweets_of_user:`
Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user's numeric user ID.

You can only pass a single username/ID per `retweets_of:` operator.

Example: `retweets_of:XDevelopers OR retweets_of:twitterapi`
See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs. | +| `context:` | Standalone | Matches Posts with a specific domain id and/or domain id, entity id pair where * represents a wildcard. To learn more about this operator, please visit our page on [Post annotations](/x-api/fundamentals/post-annotations).

You can only pass a single domain/entity per `context:` operator.

`context:domain_id.entity_id`
`context:domain_id.*`
`context:*.entity_id`

Examples:
`context:10.799022225751871488`
(`domain_id.entity_id` returns Posts matching that specific domain-entity pair)

`context:47.*`
(`domain_id.*` returns Posts matching that domain ID, with any domain-entity pair)

`context:*.799022225751871488`
(`*.entity_id` returns Posts matching that entity ID, with any domain-entity pair) | +| `entity:` | Standalone | Matches Posts with a specific entity string value. To learn more about this operator, please visit our page on [annotations](/x-api/fundamentals/post-annotations).

You can only pass a single entity per `entity:` operator.

`entity:"string declaration of entity/place"`

Examples: `entity:"Michael Jordan" OR entity:"Barcelona"` | +| `conversation_id:` | Standalone | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the `conversation_id` is added to its JSON payload.

You can only pass a single conversation ID per `conversation_id:` operator.

Example: `conversation_id:1334987486343299072 (from:XDevelopers OR from:api)` | +| `bio:` | Standalone | *Available alias:* `user_bio:`
Matches a keyword or phrase within the Post publisher's bio. This is a tokenized match within the contents of the `description` field within the [User object](/x-api/fundamentals/data-dictionary#user).

Example: `bio:developer OR bio:"data engineer" OR bio:academic` | +| `bio_name:` | Standalone | Matches a keyword within the Post publisher's user bio name. This is a tokenized match within the contents of a user's "name" field within the [User object](/x-api/fundamentals/data-dictionary#user).

Example: `bio_name:phd OR bio_name:md` | +| `bio_location:` | Standalone | *Available alias:* `user_bio_location:`
Matches Posts that are published by users whose location contains the specified keyword or phrase. This operator performs a tokenized match, similar to the normal keyword rules on the message body.

This location is part of the [User object](/x-api/fundamentals/data-dictionary#user), matches on the 'location' field, and is a non-normalized, user-generated, free-form string. It is also different from a Post's location (see `place:`).

Example: `bio_location:"big apple" OR bio_location:nyc OR bio_location:manhattan` | +| `place:` | Standalone | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

You can only pass a single place per `place:` operator.

Note: See the [GET geo/search](https://developer.x.com/content/developer-twitter/en/docs/geo/places-near-location/api-reference/get-geo-search) standard v1.1 endpoint for how to obtain X place IDs.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | +| `place_country:` | Standalone | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.

You can find a list of valid ISO codes on [Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

You can only pass a single ISO code per `place_country:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place_country:US OR place_country:MX OR place_country:CA` | +| `point_radius:` | Standalone | Matches against the `place.geo.coordinates` object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region.

`point_radius:[longitude latitude radius]`

- Units of radius supported are miles (mi) and kilometers (km)
- Radius must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees
- Rule arguments are contained within brackets, space delimited

You can only pass a single geo polygon per `point_radius:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | +| `bounding_box:` | Standalone | *Available alias:* `geo_bounding_box:`
Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region.

`bounding_box:[west_long south_lat east_long north_lat]`

- `west_long south_lat` represent the southwest corner of the bounding box where `west_long` is the longitude of that point, and `south_lat` is the latitude.
- `east_long north_lat` represent the northeast corner of the bounding box, where `east_long` is the longitude of that point, and `north_lat` is the latitude.
- Width and height of the bounding box must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees.
- Rule arguments are contained within brackets, space delimited.

You can only pass a single geo polygon per `bounding_box:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | +| `is:retweet` | Conjunction required | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator.

Example: `data @XDevelopers -is:retweet` | +| `is:reply` | Conjunction required | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a rule from delivery.

When used with the filtered stream, this operator matches on replies to an original Post, replies in quoted Posts, and replies in Retweets.

Example: `from:XDevelopers is:reply` | +| `is:quote` | Conjunction required | Returns all Quote Tweets, also known as Posts with comments.

Example: `"sentiment analysis" is:quote` | +| `is:verified` | Conjunction required | Deliver only Posts whose authors are verified by X.

Example: `#nowplaying is:verified` | +| `-is:nullcast` | Conjunction required | Removes Posts created for promotion only on ads.twitter.com that have a `source:"Twitter for Advertisers (legacy)"` or `source:"Twitter for Advertisers".`
This operator must be negated.

For more info on Nullcasted Posts, see our page on [Post availability](https://developer.x.com/content/developer-twitter/en/docs/twitter-api/v1/tweets/post-and-engage/guides/tweet-availability).

Example: `"mobile games" -is:nullcast` | +| `has:hashtags` | Conjunction required | Matches Posts that contain at least one hashtag.

Example: `from:XDevelopers -has:hashtags` | +| `has:cashtags` | Conjunction required | Matches Posts that contain a cashtag symbol (with a leading '$' character. For example, `$tag`).

Example: `#stonks has:cashtags` | +| `has:links` | Conjunction required | This operator matches Posts which contain links and media in the Post body.

Example: `from:XDevelopers announcement has:links` | +| `has:mentions` | Conjunction required | Matches Posts that mention another X user.

Example: `#nowplaying has:mentions` | +| `has:media` | Conjunction required | *Available alias:* `has:media_link`
Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites.

Example: `(kittens OR puppies) has:media` | +| `has:images` | Conjunction required | Matches Posts that contain a recognized URL to an image.

Example: `#meme has:images` | +| `has:video_link` | Conjunction required | *Available alias:* `has:videos`
Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites.

Example: `#icebucketchallenge has:video_link` | +| `has:geo` | Conjunction required | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate.

Note: Operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data.

Example: `recommend #paris has:geo -bakery` | +| `sample:` | Conjunction required | Returns a random percent sample of Posts that match a rule rather than the entire set of Posts. The percent value must be represented by an integer between 1 and 100 (for example, `sample:10` will return a random 10% sample).

This operator first reduces the scope of the stream to the percentage you specified, then the rule/filter is applied to that sampled subset. In other words, if you are using, for example, `sample:10`, each Post will have a 10% chance of being in the sample.

This operator applies to the entire rule and requires all OR'd terms to be grouped.

Example: `#nowplaying @spotify sample:15` | +| `lang:` | Conjunction required | Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

You can only pass a single BCP 47 language identifier per `lang:` operator.

Note: if no language classification can be made the provided result is 'und' (for undefined).

Example: `recommend #paris lang:en`

The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

| Language | BCP 47 |
|-|-|
| Amharic | `am` |
| Arabic | `ar` |
| Armenian | `hy` |
| Basque | `eu` |
| Bengali | `bn` |
| Bosnian | `bs` |
| Bulgarian | `bg` |
| Burmese | `my` |
| Croatian | `hr` |
| Catalan | `ca` |
| Czech | `cs` |
| Danish | `da` |
| Dutch | `nl` |
| English | `en` |
| Estonian | `et` |
| Finnish | `fi` |
| French | `fr` |
| Georgian | `ka` |
| German | `de` |
| Greek | `el` |
| Gujarati | `gu` |
| Haitian Creole | `ht` |
| Hebrew | `iw` |
| Hindi | `hi` |
| Latinized Hindi | `hi-Latn` |
| Hungarian | `hu` |
| Icelandic | `is` |
| Indonesian | `in` |
| Italian | `it` |
| Japanese | `ja` |
| Kannada | `kn` |
| Khmer | `km` |
| Korean | `ko` |
| Lao | `lo` |
| Latvian | `lv` |
| Lithuanian | `lt` |
| Malayalam | `ml` |
| Maldivian | `dv` |
| Marathi | `mr` |
| Nepali | `ne` |
| Norwegian | `no` |
| Oriya | `or` |
| Panjabi | `pa` |
| Pashto | `ps` |
| Persian | `fa` |
| Polish | `pl` |
| Portuguese | `pt` |
| Romanian | `ro` |
| Russian | `ru` |
| Serbian | `sr` |
| Simplified Chinese | `zh-CN` |
| Sindhi | `sd` |
| Sinhala | `si` |
| Slovak | `sk` |
| Slovenian | `sl` |
| Sorani Kurdish | `ckb` |
| Spanish | `es` |
| Swedish | `sv` |
| Tagalog | `tl` |
| Tamil | `ta` |
| Telugu | `te` |
| Thai | `th` |
| Tibetan | `bo` |
| Traditional Chinese | `zh-TW` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Urdu | `ur` |
| Uyghur | `ug` |
| Vietnamese | `vi` |
| Welsh | `cy` | | +| `followers_count:` | | Matches Posts when the author has a followers count within the given range.
If a single number is specified, any number equal to or higher will match.

Example: `followers_count:500`

Additionally, a range can be specified to match any number in the given range.

Example: `followers_count:1000..10000` | +| `tweets_count:` | | *Available alias:* `statuses_count:`
Matches Posts when the author has posted a number of Posts that falls within the given range.
If a single number is specified, any number equal to or higher will match.

Example: `tweets_count:1000`

Additionally, a range can be specified to match any number in the given range.

Example: `tweets_count:1000..10000` | +| `following_count:` | | *Available alias:* `friends_count:`
Matches Posts when the author has a friends count (the number of users they follow) that falls within the given range.
If a single number is specified, any number equal to or higher will match.

Example: `following_count:500`

Additionally, a range can be specified to match any number in the given range.

Example: `following_count:1000..10000` | +| `listed_count:` | | *Available alias:* `user_in_lists_count:`
Matches Posts when the author is included in the specified number of Lists.
If a single number is specified, any number equal to or higher will match.

Example: `listed_count:10`

Additionally, a range can be specified to match any number in the given range.

Example: `listed_count:10..100` | +| `url_title:` | | *Available alias:* `within_url_title:`
Performs a keyword/phrase match on the expanded URL HTML title metadata.

Example: `url_title:snow` | +| `url_description:` | | *Available alias:* `within_url_description:`
Performs a keyword/phrase match on the expanded page description metadata.

Example: `url_description:weather` | +| `url_contains:` | | Matches Posts with URLs that literally contain the given phrase or keyword. To search for patterns with punctuation in them (i.e., google.com) enclose the search term in quotes.
NOTE: This will match against the expanded URL as well.

Example: `url_contains:photos` | +| `source:` | | Matches any Post generated by the given source application. The value must be either the name of the application or the application's URL. Cannot be used alone.

Example: `source:"X for iPhone"`

Note: As an X app developer, Posts created programmatically by your application will have the source of your application Name and Website URL set in your [app settings](/resources/fundamentals/developer-apps#app-management). | +| `in_reply_to_tweet_id:` | | *Available alias:* `in_reply_to_status_id:`
Deliver only explicit Replies to the specified Post.

Example: `in_reply_to_tweet_id:1539382664746020864` | +| `retweets_of_tweet_id:` | | *Available alias:* `retweets_of_status_id:`
Deliver only explicit (or native) Retweets of the specified Post. Note that the status ID used should be the ID of an original Post and not a Retweet.

Example: `retweets_of_tweet_id:1539382664746020864` | \ No newline at end of file diff --git a/x-api/posts/search/integrate/build-a-query.mdx b/x-api/posts/search/integrate/build-a-query.mdx index 55fff475..bc099dd8 100644 --- a/x-api/posts/search/integrate/build-a-query.mdx +++ b/x-api/posts/search/integrate/build-a-query.mdx @@ -36,7 +36,7 @@ If you have Pro access, your query can be 1,024 characters long for full archive #### Operator availability -While most operators are available to any developer, there are several that are reserved for certain access levels. We list which access level each operator is available to in the [list of operators](/x-api/posts/search/integrate/build-a-query) table using the following labels: +While most operators are available to any developer, there are several that are reserved for certain access levels. We list which access level each operator is available to in the [list of operators](/x-api/posts/search/integrate/operators) table using the following labels: * **Core operators:** Available when using any [Project](/resources/fundamentals/projects). * **Advanced operators:** Available when using a Project with certain access level @@ -88,7 +88,6 @@ When combining AND and OR functionality, the following order of operations will 2. Then, operators connected with OR logic are applied - For example: * `apple OR iphone ipad` would be evaluated as `apple OR (iphone ipad)` @@ -222,46 +221,4 @@ And here is what the query would look like with the HTTP encoding, the query par `https://api.x.com/2/tweets/search/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja` -Try out the [query builder tool](https://developer.x.com/apitools/query?query=) for additional support.  - -### Operators - -**Note:** For some operators, an alternate name, or alias, is available. - -| **Operator** | **Type** | **Description** | -|:-------------|:---------|:-----------------| -| `keyword` | Standalone | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters.

For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your query. To match strings containing punctuation (for example coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes.

Example: `pepsi OR cola OR "coca cola"` | -| `emoji` | Standalone | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body.

Note that if an emoji has a variant, you must wrap it in double quotes to add to a query.

Example: `(😃 OR 😡) 😬` | -| `"exact phrase match"` | Standalone | Matches the exact phrase within the body of a Post.

Example: `("X API" OR #v2) -"recent search"` | -| `#` | Standalone | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post.

This operator performs an exact match, NOT a tokenized match, meaning the rule `#thanku` will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext.

Example: `#thankunext #fanart OR @arianagrande` | -| `@` | Standalone | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character).

Example: `(@XDevelopers OR @API) -@X` | -| `$` | Standalone | Matches any Post that contains the specified 'cashtag' (where the leading character of the token is the $ character).

Note that the cashtag operator relies on X's 'symbols' entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself.

Example: `$twtr OR @XDevelopers -$fb` | -| `from:` | Standalone | Matches any Post from a specific user.
The value can be either the username (excluding the @ character) or the user’s numeric user ID.

You can only pass a single username/ID per `from:` operator.

Example: `from:XDevelopers OR from:API -from:X` | -| `to:` | Standalone | Matches any Post that is in reply to a particular user.
The value can be either the username (excluding the @ character) or the user’s numeric user ID.

You can only pass a single username/ID per `to:` operator.

Example: `to:XDevelopers OR to:API -to:X` | -| `url:` | Standalone | Performs a tokenized match on any validly-formatted URL of a Post.

This operator matches on the contents of both the `url` or `expanded_url` fields. For example, a Post containing "You should check out X Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.twitter.com) will match both the following rules:

`from:XDevelopers url:"https://developer.twitter.com"` (because it will match the contents of `entities.urls.expanded_url`)

`from:XDevelopers url:"https://t.co"` (because it will match the contents of `entities.urls.url`)

Tokens and phrases containing punctuation or special characters should be double-quoted (for example, `url:"/developer"`). Similarly, to match on a specific protocol, enclose in double-quotes (for example, `url:"https://developer.twitter.com"`). | -| `retweets_of:` | Standalone | Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID.

You can only pass a single username/ID per `retweets_of:` operator.

Example: `retweets_of:twitterdev OR retweets_of:twitterapi` | -| `in_reply_to_tweet_id:` | Standalone | *Available alias:* `in_reply_to_status_id:`
Matches on replies to the specified Post.

Example: `in_reply_to_tweet_id:1539382664746020864` | -| `retweets_of_tweet_id:` | Standalone | *Available alias:* `retweets_of_status_id:`
Matches on explicit (or native) Retweets of the specified Post. Note that the Post ID used should be the ID of an original Post and not a Retweet.

Example: `retweets_of_tweet_id:1539382664746020864` | -| `quotes_of_tweet_id:` | Standalone | *Available alias:* `quotes_of_status_id:`
Matches on Quote Tweets of the specified Post. Note that the Post ID used should be the ID of an original Post and not a Quote Tweet.

Example: `quotes_of_tweet_id:1539382664746020864` | -| `context:` | Standalone | Matches Posts with a specific domain id/entity id pair. To learn more about this operator, please visit our page on [annotations](/x-api/fundamentals/post-annotations).

You can only pass a single domain/entity per `context:` operator.

`context:domain_id.entity_id`

However, you can combine multiple domain/entities using the OR operator:

`(context:47.1139229372198469633 OR context:11.1088514520308342784)`

Examples:
`context:10.799022225751871488` (`domain_id.entity_id` returns Posts matching that specific domain-entity pair) | -| `entity:` | Standalone | Matches Posts with a specific entity string value. To learn more about this operator, please visit our page on [annotations](/x-api/fundamentals/post-annotations).
**Please note** that this is only available with recent search.

You can only pass a single `entity:` operator.

`entity:"string declaration of entity/place"`

Examples: `entity:"Michael Jordan" OR entity:"Barcelona"` | -| `conversation_id:` | Standalone | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the `conversation_id` is added to its JSON payload.

You can only pass a single conversation ID per `conversation_id:` operator.

Example: `conversation_id:1334987486343299072 (from:XDevelopers OR from:api)` | -| `list:` | Standalone | **NEW** Matches Posts posted by users who are members of a specified list.

For example, if @XDevelopers and @api were members of List 123, and you included `list:123` in your query, your response will only contain Posts that have been published by those accounts. You can find List IDs by using the [List lookup](/x-api/lists/list-lookup/introduction) endpoint.

**Please note** that you can only use a single `list:` operator per query, and you can only specify a single List per `list:` operator.

Example: `list:123` | -| `place:` | Standalone | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

You can only pass a single place per `place:` operator.

Note: See the [GET geo/search](https://developer.x.com/content/developer-twitter/en/docs/geo/places-near-location/api-reference/get-geo-search) standard v1.1 endpoint for how to obtain X place IDs.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | -| `place_country:` | Standalone | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.

You can find a list of valid ISO codes on [Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

You can only pass a single ISO code per `place_country:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place_country:US OR place_country:MX OR place_country:CA` | -| `point_radius:` | Standalone | Matches against the `place.geo.coordinates` object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region.

`point_radius:[longitude latitude radius]`

- Units of radius supported are miles (mi) and kilometers (km)
- Radius must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees
- Rule arguments are contained within brackets, space delimited

You can only pass a single geo polygon per `point_radius:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | -| `bounding_box:` | Standalone | *Available alias:* `geo_bounding_box:`
Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region.

`bounding_box:[west_long south_lat east_long north_lat]`

- `west_long south_lat` represent the southwest corner of the bounding box where `west_long` is the longitude of that point, and `south_lat` is the latitude.
- `east_long north_lat` represent the northeast corner of the bounding box, where `east_long` is the longitude of that point, and `north_lat` is the latitude.
- Width and height of the bounding box must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees.
- Rule arguments are contained within brackets, space delimited.

You can only pass a single geo polygons per `bounding_box:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | -| `is:retweet` | Conjunction required | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator.

Example: `data @XDevelopers -is:retweet` | -| `is:reply` | Conjunction required | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a query from delivery.

Note: This operator is also available with the filtered stream endpoint. When used with filtered stream, this operator matches on replies to an original Post, replies in quoted Tweets, and replies in Retweets.

Example: `from:XDevelopers is:reply` | -| `is:quote` | Conjunction required | Returns all Quote Tweets, also known as Posts with comments.

Example: `"sentiment analysis" is:quote` | -| `is:verified` | Conjunction required | Deliver only Posts whose authors are verified by X.

Example: `#nowplaying is:verified` | -| `-is:nullcast` | Conjunction required | Removes Posts created for promotion only on ads.twitter.com that have a `"source":"Twitter for Advertisers (legacy)"` or `"source":"Twitter for Advertisers"`.
This operator must be negated.

For more info on Nullcasted Posts, see our page on [Post availability](https://developer.x.com/content/developer-twitter/en/docs/twitter-api/v1/tweets/post-and-engage/guides/tweet-availability).

Example: `"mobile games" -is:nullcast` | -| `has:hashtags` | Conjunction required | Matches Posts that contain at least one hashtag.

Example: `from:XDevelopers -has:hashtags` | -| `has:cashtags` | Conjunction required | Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, `$tag`).

Example: `#stonks has:cashtags` | -| `has:links` | Conjunction required | This operator matches Posts which contain links and media in the Post body.

Example: `from:XDevelopers announcement has:links` | -| `has:mentions` | Conjunction required | Matches Posts that mention another X user.

Example: `#nowplaying has:mentions` | -| `has:media` | Conjunction required | *Available alias:* `has:media_link`
Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites.

Example: `(kittens OR puppies) has:media` | -| `has:images` | Conjunction required | Matches Posts that contain a recognized URL to an image.

Example: `#meme has:images` | -| `has:video_link` | Conjunction required | *Available alias:* `has:videos`
Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites.

Example: `#icebucketchallenge has:video_link` | -| `has:geo` | Conjunction required | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate.

Note: Operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data.

Example: `recommend #paris has:geo -bakery` | -| `lang:` | Conjunction required | Matches Posts that have been classified by X as being of a particular language (if, and only if, the Post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND'ing together multiple languages will yield no results.

You can only pass a single BCP 47 language identifier per `lang:` operator.

Note: if no language classification can be made the provided result is ‘und’ (for undefined).

Example: `recommend #paris lang:en`

The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

Amharic: `am` \| German: `de` \| Malayalam: `ml` \| Slovak: `sk`
Arabic: `ar` \| Greek: `el` \| Maldivian: `dv` \| Slovenian: `sl`
Armenian: `hy` \| Gujarati: `gu` \| Marathi: `mr` \| Sorani Kurdish: `ckb`
Basque: `eu` \| Haitian Creole: `ht` \| Nepali: `ne` \| Spanish: `es`
Bengali: `bn` \| Hebrew: `iw` \| Norwegian: `no` \| Swedish: `sv`
Bosnian: `bs` \| Hindi: `hi` \| Oriya: `or` \| Tagalog: `tl`
Bulgarian: `bg` \| Latinized Hindi: `hi-Latn` \| Panjabi: `pa` \| Tamil: `ta`
Burmese: `my` \| Hungarian: `hu` \| Pashto: `ps` \| Telugu: `te`
Croatian: `hr` \| Icelandic: `is` \| Persian: `fa` \| Thai: `th`
Catalan: `ca` \| Indonesian: `in` \| Polish: `pl` \| Tibetan: `bo`
Czech: `cs` \| Italian: `it` \| Portuguese: `pt` \| Traditional Chinese: `zh-TW`
Danish: `da` \| Japanese: `ja` \| Romanian: `ro` \| Turkish: `tr`
Dutch: `nl` \| Kannada: `kn` \| Russian: `ru` \| Ukrainian: `uk`
English: `en` \| Khmer: `km` \| Serbian: `sr` \| Urdu: `ur`
Estonian: `et` \| Korean: `ko` \| Simplified Chinese: `zh-CN` \| Uyghur: `ug`
Finnish: `fi` \| Lao: `lo` \| Sindhi: `sd` \| Vietnamese: `vi`
French: `fr` \| Latvian: `lv` \| Sinhala: `si` \| Welsh: `cy`
Georgian: `ka` \| Lithuanian: `lt` | \ No newline at end of file +Try out the [query builder tool](https://developer.x.com/apitools/query?query=) for additional support. \ No newline at end of file diff --git a/x-api/posts/search/integrate/operators.mdx b/x-api/posts/search/integrate/operators.mdx new file mode 100644 index 00000000..19c420b9 --- /dev/null +++ b/x-api/posts/search/integrate/operators.mdx @@ -0,0 +1,51 @@ +--- +title: Search Query Operators +sidebarTitle: Operators +--- + +This page provides a list of operators availble when [building a query](/x-api/posts/search/integrate/build-a-query) for the Search v2 API endpoints. + +## List of operators + +**Note:** For some operators, an alternate name, or alias, is available. + +| **Operator** | **Type** | **Description** | +|:-------------|:---------|:-----------------| +| `keyword` | Standalone | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters.

For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your query. To match strings containing punctuation (for example coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes.

Example: `pepsi OR cola OR "coca cola"` | +| `emoji` | Standalone | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body.

Note that if an emoji has a variant, you must wrap it in double quotes to add to a query.

Example: `(😃 OR 😡) 😬` | +| `"exact phrase match"` | Standalone | Matches the exact phrase within the body of a Post.

Example: `("X API" OR #v2) -"recent search"` | +| `#` | Standalone | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post.

This operator performs an exact match, NOT a tokenized match, meaning the rule `#thanku` will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext.

Example: `#thankunext #fanart OR @arianagrande` | +| `@` | Standalone | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character).

Example: `(@XDevelopers OR @API) -@X` | +| `$` | Standalone | Matches any Post that contains the specified 'cashtag' (where the leading character of the token is the $ character).

Note that the cashtag operator relies on X's 'symbols' entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself.

Example: `$twtr OR @XDevelopers -$fb` | +| `from:` | Standalone | Matches any Post from a specific user.
The value can be either the username (excluding the @ character) or the user’s numeric user ID.

You can only pass a single username/ID per `from:` operator.

Example: `from:XDevelopers OR from:API -from:X` | +| `to:` | Standalone | Matches any Post that is in reply to a particular user.
The value can be either the username (excluding the @ character) or the user’s numeric user ID.

You can only pass a single username/ID per `to:` operator.

Example: `to:XDevelopers OR to:API -to:X` | +| `url:` | Standalone | Performs a tokenized match on any validly-formatted URL of a Post.

This operator matches on the contents of both the `url` or `expanded_url` fields. For example, a Post containing "You should check out X Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.twitter.com) will match both the following rules:

`from:XDevelopers url:"https://developer.twitter.com"` (because it will match the contents of `entities.urls.expanded_url`)

`from:XDevelopers url:"https://t.co"` (because it will match the contents of `entities.urls.url`)

Tokens and phrases containing punctuation or special characters should be double-quoted (for example, `url:"/developer"`). Similarly, to match on a specific protocol, enclose in double-quotes (for example, `url:"https://developer.twitter.com"`). | +| `retweets_of:` | Standalone | Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID.

You can only pass a single username/ID per `retweets_of:` operator.

Example: `retweets_of:twitterdev OR retweets_of:twitterapi` | +| `in_reply_to_tweet_id:` | Standalone | *Available alias:* `in_reply_to_status_id:`
Matches on replies to the specified Post.

Example: `in_reply_to_tweet_id:1539382664746020864` | +| `retweets_of_tweet_id:` | Standalone | *Available alias:* `retweets_of_status_id:`
Matches on explicit (or native) Retweets of the specified Post. Note that the Post ID used should be the ID of an original Post and not a Retweet.

Example: `retweets_of_tweet_id:1539382664746020864` | +| `quotes_of_tweet_id:` | Standalone | *Available alias:* `quotes_of_status_id:`
Matches on Quote Tweets of the specified Post. Note that the Post ID used should be the ID of an original Post and not a Quote Tweet.

Example: `quotes_of_tweet_id:1539382664746020864` | +| `context:` | Standalone | Matches Posts with a specific domain id/entity id pair. To learn more about this operator, please visit our page on [annotations](/x-api/fundamentals/post-annotations).

You can only pass a single domain/entity per `context:` operator.

`context:domain_id.entity_id`

However, you can combine multiple domain/entities using the OR operator:

`(context:47.1139229372198469633 OR context:11.1088514520308342784)`

Examples:
`context:10.799022225751871488` (`domain_id.entity_id` returns Posts matching that specific domain-entity pair) | +| `entity:` | Standalone | Matches Posts with a specific entity string value. To learn more about this operator, please visit our page on [annotations](/x-api/fundamentals/post-annotations).
**Please note** that this is only available with recent search.

You can only pass a single `entity:` operator.

`entity:"string declaration of entity/place"`

Examples: `entity:"Michael Jordan" OR entity:"Barcelona"` | +| `conversation_id:` | Standalone | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the `conversation_id` is added to its JSON payload.

You can only pass a single conversation ID per `conversation_id:` operator.

Example: `conversation_id:1334987486343299072 (from:XDevelopers OR from:api)` | +| `list:` | Standalone | Matches Posts posted by users who are members of a specified list.

For example, if @XDevelopers and @api were members of List 123, and you included `list:123` in your query, your response will only contain Posts that have been published by those accounts. You can find List IDs by using the [List lookup](/x-api/lists/list-lookup/introduction) endpoint.

**Please note** that you can only use a single `list:` operator per query, and you can only specify a single List per `list:` operator.

Example: `list:123` | +| `place:` | Standalone | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

You can only pass a single place per `place:` operator.

Note: See the [GET geo/search](https://developer.x.com/content/developer-twitter/en/docs/geo/places-near-location/api-reference/get-geo-search) standard v1.1 endpoint for how to obtain X place IDs.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | +| `place_country:` | Standalone | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.

You can find a list of valid ISO codes on [Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

You can only pass a single ISO code per `place_country:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `place_country:US OR place_country:MX OR place_country:CA` | +| `point_radius:` | Standalone | Matches against the `place.geo.coordinates` object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region.

`point_radius:[longitude latitude radius]`

- Units of radius supported are miles (mi) and kilometers (km)
- Radius must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees
- Rule arguments are contained within brackets, space delimited

You can only pass a single geo polygon per `point_radius:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | +| `bounding_box:` | Standalone | *Available alias:* `geo_bounding_box:`
Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region.

`bounding_box:[west_long south_lat east_long north_lat]`

- `west_long south_lat` represent the southwest corner of the bounding box where `west_long` is the longitude of that point, and `south_lat` is the latitude.
- `east_long north_lat` represent the northeast corner of the bounding box, where `east_long` is the longitude of that point, and `north_lat` is the latitude.
- Width and height of the bounding box must be less than 25mi
- Longitude is in the range of ±180
- Latitude is in the range of ±90
- All coordinates are in decimal degrees.
- Rule arguments are contained within brackets, space delimited.

You can only pass a single geo polygons per `bounding_box:` operator.

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.

Example: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | +| `min_likes` | Standalone | Matches Posts that have at minimum the specified number of likes. | +| `min_replies` | Standalone | Matches Posts that have at minimum the specified number of replies. | +| `min_reposts` | Standalone | Matches Posts that have at minimum the specified number of reposts. | +| `is:retweet` | Conjunction required | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator.

Example: `data @XDevelopers -is:retweet` | +| `is:reply` | Conjunction required | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a query from delivery.

Note: This operator is also available with the filtered stream endpoint. When used with filtered stream, this operator matches on replies to an original Post, replies in quoted Tweets, and replies in Retweets.

Example: `from:XDevelopers is:reply` | +| `is:quote` | Conjunction required | Returns all Quote Tweets, also known as Posts with comments.

Example: `"sentiment analysis" is:quote` | +| `is:verified` | Conjunction required | Deliver only Posts whose authors are verified by X.

Example: `#nowplaying is:verified` | +| `-is:nullcast` | Conjunction required | Removes Posts created for promotion only on ads.twitter.com that have a `"source":"Twitter for Advertisers (legacy)"` or `"source":"Twitter for Advertisers"`.
This operator must be negated.

For more info on Nullcasted Posts, see our page on [Post availability](https://developer.x.com/content/developer-twitter/en/docs/twitter-api/v1/tweets/post-and-engage/guides/tweet-availability).

Example: `"mobile games" -is:nullcast` | +| `has:hashtags` | Conjunction required | Matches Posts that contain at least one hashtag.

Example: `from:XDevelopers -has:hashtags` | +| `has:cashtags` | Conjunction required | Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, `$tag`).

Example: `#stonks has:cashtags` | +| `has:links` | Conjunction required | This operator matches Posts which contain links and media in the Post body.

Example: `from:XDevelopers announcement has:links` | +| `has:mentions` | Conjunction required | Matches Posts that mention another X user.

Example: `#nowplaying has:mentions` | +| `has:media` | Conjunction required | *Available alias:* `has:media_link`
Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites.

Example: `(kittens OR puppies) has:media` | +| `has:images` | Conjunction required | Matches Posts that contain a recognized URL to an image.

Example: `#meme has:images` | +| `has:video_link` | Conjunction required | *Available alias:* `has:videos`
Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites.

Example: `#icebucketchallenge has:video_link` | +| `has:geo` | Conjunction required | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate.

Note: Operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data.

Example: `recommend #paris has:geo -bakery` | +| `lang:` | Conjunction required | Matches Posts that have been classified by X as being of a particular language (if, and only if, the Post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND'ing together multiple languages will yield no results.

You can only pass a single BCP 47 language identifier per `lang:` operator.

Note: if no language classification can be made the provided result is ‘und’ (for undefined).

Example: `recommend #paris lang:en`

The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

Amharic: `am` \| German: `de` \| Malayalam: `ml` \| Slovak: `sk`
Arabic: `ar` \| Greek: `el` \| Maldivian: `dv` \| Slovenian: `sl`
Armenian: `hy` \| Gujarati: `gu` \| Marathi: `mr` \| Sorani Kurdish: `ckb`
Basque: `eu` \| Haitian Creole: `ht` \| Nepali: `ne` \| Spanish: `es`
Bengali: `bn` \| Hebrew: `iw` \| Norwegian: `no` \| Swedish: `sv`
Bosnian: `bs` \| Hindi: `hi` \| Oriya: `or` \| Tagalog: `tl`
Bulgarian: `bg` \| Latinized Hindi: `hi-Latn` \| Panjabi: `pa` \| Tamil: `ta`
Burmese: `my` \| Hungarian: `hu` \| Pashto: `ps` \| Telugu: `te`
Croatian: `hr` \| Icelandic: `is` \| Persian: `fa` \| Thai: `th`
Catalan: `ca` \| Indonesian: `in` \| Polish: `pl` \| Tibetan: `bo`
Czech: `cs` \| Italian: `it` \| Portuguese: `pt` \| Traditional Chinese: `zh-TW`
Danish: `da` \| Japanese: `ja` \| Romanian: `ro` \| Turkish: `tr`
Dutch: `nl` \| Kannada: `kn` \| Russian: `ru` \| Ukrainian: `uk`
English: `en` \| Khmer: `km` \| Serbian: `sr` \| Urdu: `ur`
Estonian: `et` \| Korean: `ko` \| Simplified Chinese: `zh-CN` \| Uyghur: `ug`
Finnish: `fi` \| Lao: `lo` \| Sindhi: `sd` \| Vietnamese: `vi`
French: `fr` \| Latvian: `lv` \| Sinhala: `si` \| Welsh: `cy`
Georgian: `ka` \| Lithuanian: `lt` | \ No newline at end of file From 4060fdb0933a61d6b1ed82083b3969bb9932a1a8 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Fri, 7 Nov 2025 12:17:51 -0800 Subject: [PATCH 2/2] Fix title --- x-api/posts/search/integrate/operators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-api/posts/search/integrate/operators.mdx b/x-api/posts/search/integrate/operators.mdx index 19c420b9..3b92361b 100644 --- a/x-api/posts/search/integrate/operators.mdx +++ b/x-api/posts/search/integrate/operators.mdx @@ -1,5 +1,5 @@ --- -title: Search Query Operators +title: Search Operators sidebarTitle: Operators ---