Filters are field:value clauses inside the q parameter. Combine them freely with free-text terms and boolean operators - see 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.
| 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.
| 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.
| 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.
| Filter | Example | Meaning |
|---|---|---|
performance_score: | performance_score:>8 | Engagement score of the thread - integer 0-10 |
| 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.
