Query surface

Filters

Twenty-plus exact filters, numeric signal ranges, facet aggregation and pagination — combinable in one request, on every plan.

Publication

Parameter	Matches	Example
`source`	Publisher domain	`bbc.co.uk`
`source_type`	Kind of publication	`web`
`publisher_country`	Where the publisher is based	`US`
`language`	Source language, ISO-639-3	`hin`
`author`	Byline	`jane doe`

Place

Parameter	Matches	Example
`country`	Country the article is about (FIPS 10-4)	`GM`
`city`	City mentioned	`Berlin`
`region`	Administrative region mentioned	`Bavaria`
`location`	Any place name mentioned	`Rhine`
`location_id`	Exact gazetteer identifier	`-1746443`

Subject and entities

Parameter	Matches	Example
`topic`	Canonical topic identifier	`EPU_POLICY`
`organization`	Organisation mentioned	`european union`
`person`	Person mentioned	`benjamin netanyahu`
`name`	Any proper name mentioned	`Ministry of Finance`

Statements and figures

Parameter	Matches	Example
`quote_verb`	Verb introducing a quotation	`warned`
`amount_object`	What a quantity refers to	`barrels`
`mentioned_date`	A date the article refers to	`20260801`

Time and grouping

Parameter	Matches	Example
`from / to`	Publication window, to the second	`20260729T140000`
`story_id`	One clustered story	`st_9f2…`

Signal ranges

Every article carries scored language signals across industry, business and risk groups. Filter on a range rather than an exact value, and stack constraints — all of them must match.

# energy coverage carrying financial-stress language
GET /search?signal=signal_energy&signal_min=0.3

# stack several: supply disruption AND financial negativity
GET /search?signals=signal_supply_disruption:0.2,signal_financial_negative:0.15

What the signals are and how to use them →

Facets: ask what values exist

Rather than guessing which countries, topics or outlets are worth filtering on, ask. Any filterable field can be requested as a facet, returning values with counts across the whole result set.

GET /search?q=semiconductors&facets=country,organization,language&facet_limit=25

Responses include how much sits outside the returned buckets, so a truncated facet is visible rather than mistaken for the complete distribution. This is what the coverage figures on this site are generated from.

Pagination

Results carry offset, limit, has_more and a total. The total is marked exact for keyword and metadata queries and approximate for ranked semantic modes, so you know whether a count can be relied on or only compared.

Combining them

Filters are conjunctive: every constraint must match. That makes narrow queries cheap to express and makes it easy to over-constrain into an empty result set, so build up rather than starting from everything at once.

# German-language coverage about France, energy sector,
# from publishers based in Germany, last 48 hours
GET /stories
  ?language=deu
  &country=FR
  &publisher_country=DE
  &signal=signal_energy&signal_min=0.25
  &from=20260729T000000