Count matching articles

Plain-language description of the news you want, e.g. "Elon Musk, Tesla, news for the last 10 days". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt).

Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.

Comma-separated article IDs (max 5)

Search in article titles. Supports phrase search with proximity: "climate change"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110.

Exclude articles containing this text in the title

Filter articles whose title starts with the given text. Same 31-day window limit as title

Filter articles whose title ends with the given text. Same 31-day window limit as title

Filter articles whose title matches the given pattern. Same 31-day window limit as title

Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601

Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)

End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)

Comma-separated ISO 639-1 language codes (max 3)

Exclude articles in these languages (comma-separated, max 3)

Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)

Exclude sources from these countries (comma-separated, max 3)

Minimum Open PageRank score

Maximum Open PageRank score

Comma-separated source IDs (max 3)

Exclude these source IDs (comma-separated, max 3)

Comma-separated source domains (max 3)

Exclude these source domains (comma-separated, max 3)

Filter by media bias (comma-separated). Values: left, center, right

Exclude sources with this media bias (comma-separated). Values: left, center, right

Filter by premium source status

Filter by verified source status

Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000

Exclude these categories (comma-separated, max 3)

Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news

Exclude these topics (comma-separated, max 3)

Comma-separated industry IDs (max 3)

Exclude these industries (comma-separated, max 3)

Comma-separated entity IDs (max 3)

Exclude these entity IDs (comma-separated, max 3)

Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293.

Minimum sentiment score toward the entity

Maximum sentiment score toward the entity

Filter by person name (comma-separated, max 3)

Exclude articles mentioning these persons (comma-separated, max 3)

Filter by organization name (comma-separated, max 3)

Exclude articles mentioning these organizations (comma-separated, max 3)

Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218

Exclude articles mentioning these locations (comma-separated, max 3)

Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222

Exclude articles mentioning these brands (comma-separated, max 3)

Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224

Exclude articles mentioning these disasters (comma-separated, max 3)

Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226

Exclude articles mentioning these diseases (comma-separated, max 3)

Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228

Exclude articles mentioning these events (comma-separated, max 3)

Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250

Exclude articles mentioning these sports (comma-separated, max 3)

Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche

Filter by event category

Exclude these event types (comma-separated, max 5)

Exact overall sentiment score

Minimum overall sentiment score

Maximum overall sentiment score

Overall sentiment polarity

Exact title sentiment score

Minimum title sentiment score

Maximum title sentiment score

Title sentiment polarity

Exact body sentiment score

Minimum body sentiment score

Maximum body sentiment score

Body sentiment polarity

Filter for mixed sentiment (title polarity != body polarity)

Filter for consistent sentiment (title polarity == body polarity)

Filter by clickbait detection

Minimum sentiment gap between title and body

Maximum sentiment gap between title and body

Exact number of images

Minimum number of images

Maximum number of images

Minimum image width in pixels

Maximum image width in pixels

Minimum image height in pixels

Maximum image height in pixels

Exact number of videos

Minimum number of videos

Maximum number of videos

Filter articles with/without images

Filter articles with/without videos

Filter articles with high-quality images (>= 1200px width)

Filter articles with both images and videos

Filter articles with landscape-oriented media

Filter articles with portrait-oriented media

Filter articles with 2+ images

Filter articles with Full HD images (>= 1920px width)

Filter articles with 4K images (>= 3840px width)

Filter articles with mobile-optimized images (320-800px width)

Filter articles with Instagram-ready images (>= 1080px + aspect ratio)

Filter articles with Twitter Card-ready images (>= 800px + landscape)

Filter articles with consistent image dimensions

Filter articles with thumbnail images (<= 300px width)

Filter articles with social share images (>= 1200x630px)

Filter articles with both image and video media types

Exact Flesch-Kincaid grade level

Minimum Flesch-Kincaid grade level

Maximum Flesch-Kincaid grade level

Exact Flesch Reading Ease score

Minimum Flesch Reading Ease score

Maximum Flesch Reading Ease score

Exact Automated Readability Index

Minimum Automated Readability Index

Maximum Automated Readability Index

Difficulty level

Target audience

Exact reading age

Minimum reading age

Maximum reading age

Filter for easy-to-read articles (Flesch Reading Ease >= 60)

Filter for difficult-to-read articles (Flesch Reading Ease < 40)

Exact read time in minutes

Minimum read time in minutes

Maximum read time in minutes

Filter for long reads (>= 5 minutes)

Filter for short reads (< 3 minutes)

Filter for quick reads (<= 2 minutes)

Filter for medium-length reads (3-7 minutes)

Filter for deep dives (>= 10 minutes)

Bounding box: minLat,maxLat,minLng,maxLng

Filter articles with/without geo-location data

Latitude for radius search

Longitude for radius search

Search radius in kilometers (requires location.lat and location.lng)

Minimum distance from point in km

Filter duplicate/unique articles

Filter paywalled articles

Filter breaking news articles

Filter high-quality articles (not duplicate, rank >= 5, has images, has author)

Comma-separated author IDs (max 3)

Exclude these author IDs (comma-separated, max 3)

Filter by author name (comma-separated, max 3)

Exclude articles by these authors (comma-separated, max 3)

Filter articles with/without author

Include user_input in response for debugging

API key (alternative to X-API-Key header)

Number of articles matching the filters