# Filters

Filters are `field:value` clauses inside the `q` parameter. Combine them freely with free-text terms and boolean operators - see [Query Syntax](news-blogs-forums-query-syntax) - to narrow results to exactly the sources, languages, and entities you care about.

> [!NOTE]
> Filter values are case-insensitive, and values containing spaces must be quoted. An unknown value is not rejected - it just returns 0 results. Add `warning=true` to the request to get validation warnings in the response.

## Source

| Filter | Example | Meaning |
| --- | --- | --- |
| `site:` | `site:cnn.com` | Posts from a domain |
| `site_full:` | `site_full:forums.example.com` | Exact subdomain |
| `site_suffix:` | `site_suffix:co.uk` | Domain suffix |
| `site_section:` | `site_section:business` | Section of the site |
| `site_title:` | `site_title:"morning post"` | Name of the site |
| `section_title:` | `section_title:sports` | Title of the site section |
| `country:` | `country:US` | Source country - ISO 3166-1 alpha-2 code; use `GB` for the United Kingdom (not `UK`) |
| `domain_rank:` | `domain_rank:<1000` | Domain rank - integer 1-1,000,000 (Tranco top sites; lower = more popular) |
| `site_category:` | `site_category:tech` | Category of the site - curated snake_case taxonomy (see below) |
| `licensing_agency:` | `licensing_agency:NLA` | Posts from sources licensed by an agency - `NLA`, `NCA`, or `CFC` |

`site_category:` values come from a large curated taxonomy of snake_case names - for example `tech`, `financial_news`, `world_soccer`, `travel`, `politics`, `health`, `music`, `real_estate`.

## Content

| Filter | Example | Meaning |
| --- | --- | --- |
| `title:` | `title:bitcoin` | Term in the post title |
| `text:` | `text:"supply chain"` | Term in the post body |
| `language:` | `language:english` | Post language - lowercase full English name (see list below) |
| `category:` | `category:politics` | Post category - one of 17 IPTC-based categories (see below) |
| `topic:` | `topic:"climate change"` | Post topic - finer-grained than `category:` (see below) |
| `sentiment:` | `sentiment:negative` | Post sentiment - `positive`, `negative`, or `neutral` |
| `author:` | `author:"jane doe"` | Post author |
| `crawled:` | `crawled:>1751713632000` | Crawl time (Unix milliseconds) |
| `published:` | `published:>1751713632000` | Publish time (Unix milliseconds) |
| `external_links:` | `external_links:github.com` | Posts linking to a URL or domain |
| `breaking:` | `breaking:true` | Boolean flag - likewise `has_canonical:`, `webz_reporter:`, `ai_allow:`, and `syndication.syndicated:` (all `true`/`false`) |

`category:` takes one of 17 values - case-insensitive, quote multi-word values (e.g. `category:"human interest"`): `Arts, Culture and Entertainment` · `Crime, Law and Justice` · `Disaster and Accident` · `Economy, Business and Finance` · `Education` · `Environment` · `Health` · `Human Interest` · `Labor` · `Lifestyle and Leisure` · `Politics` · `Religion and Belief` · `Science and Technology` · `Social Issue` · `Sport` · `War, Conflict and Unrest` · `Weather`.

`topic:` supports 629 topics derived from IPTC levels 2 and 3 and grouped under the 17 categories. Values are case-insensitive; quote values containing spaces. Examples include `election`, `economy`, `climate change`, `cyber crime`, `cancer`, `tennis`, `terrorism`, and `cinema`.

Topic classification supports English, Spanish, French, Italian, Catalan, Portuguese, Chinese, Traditional Chinese, Arabic, German, Russian, and Hindi. Trust-based filtering may also classify content in additional languages.

`language:` accepts 76 values - lowercase full English names: afrikaans, albanian, amharic, arabic, armenian, azerbaijani, basque, belarusian, bengali, bulgarian, burmese, catalan, cherokee, chinese, chineset, croatian, czech, danish, dhivehi, dutch, english, estonian, finnish, french, galician, georgian, german, greek, gujarati, hebrew, hindi, hungarian, icelandic, indonesian, inuktitut, irish, italian, japanese, kannada, khmer, korean, kurdish, laothian, latvian, lithuanian, macedonian, malay, malayalam, maltese, norwegian, oriya, persian, polish, portuguese, punjabi, romanian, russian, serbian, sinhalese, slovak, slovenian, spanish, swahili, swedish, syriac, tagalog, tamil, telugu, thai, tibetan, turkish, ukrainian, urdu, vietnamese, welsh, yiddish.

## Entities

| Filter | Example | Meaning |
| --- | --- | --- |
| `person:` | `person:"elon musk"` | Person mentioned, any sentiment |
| `organization:` | `organization:nvidia` | Organization mentioned, any sentiment |
| `location:` | `location:paris` | Location mentioned, any sentiment |
| `person.positive:` | `person.positive:"taylor swift"` | Person with positive sentiment (also `.negative`, `.neutral`; same for `organization` and `location`) |
| `ticker:` | `ticker:AAPL` | Stock ticker of a mentioned organization |
| `exchange:` | `exchange:NASDAQ` | Stock exchange code, e.g. `NASDAQ`, `NYSE`, `LON` |

Entities are extracted from posts in English, German, Spanish, and Italian.

## Threads & engagement

| Filter | Example | Meaning |
| --- | --- | --- |
| `performance_score:` | `performance_score:>8` | Engagement score of the thread - integer `0`-`10` |

## Trust

| Filter | Example | Meaning |
| --- | --- | --- |
| `trust.bias:` | `trust.bias:center` | Political bias of the source - `left`, `center`, or `right` |
| `trust.category:` | `trust.category:trusted_news` | Trust category - `trusted_news`, `fake_news`, or `satirical_news` |
| `trust.source.type:` | `trust.source.type:newsroom` | Source type |
| `trust.top_news:` | `trust.top_news:top_news_us` | Curated top-news sources - `top_news` (all) or `top_news_{country}`, e.g. `top_news_us`, `top_news_gb` |

Supported `trust.source.type` values are `newsroom`, `gov_news`, and `local_news`.

> [!NOTE]
> Filtering by a `trust.source.type` value requires that feature on your plan - otherwise the request returns `403`.

> [!TIP]
> When your query contains a single `language:` filter, text matching automatically uses a language-appropriate analyzer for better results in Arabic, Russian, Spanish, and French.