# 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.

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:health | site_category is derived from the categories of the site's posts. A site is assigned a category based on the most common category values across its posts. |
| licensing_agency: | licensing_agency:NLA | Posts from sources licensed by an agency - NLA, NCA, or CFC |

## 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`.

Filtering by a \`trust.source.type\` value requires that feature on your plan - otherwise the request returns \`403\`.

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.