Skip to main content
One task, end to end: watch what is happening to a company across news, government awards and physical assets. It takes four calls, and the shape of it generalises to almost everything else you will build here. The whole design rests on one idea: resolve a name to an id once, then never resolve it again.
1

Resolve the name

Never filter by a company name string. Names are ambiguous, they change, and every surface spells them differently. Ask the resolver instead:
Take the entity_id from the best match — an e_… spine id. That one string is the join key for everything below.
An empty result for a valid-looking name usually means the entity genuinely is not in the corpus, not that the query is wrong. The resolver returns no match rather than a guess.
2

What is happening to it

sort=significance is the default and the one you want for monitoring — it ranks by how much the event matters, not by how recently it arrived. Sorting by recency gives you a feed dominated by whatever a wire service published in the last hour.Start wide. The most common mistake on this API is stacking four filters on the first call and concluding the data is missing when the empty result is really your AND.
3

Read the evidence

An event is a claim; the articles are why we made it. Every event links to the story it came from:
Then /stories/{story_id}/articles for the source URLs. Build citation into the feed from the start — an alert nobody can verify gets ignored the second time it fires.
4

Fan out with the same id

This is the payoff. The entity_id from step 1 works unchanged on every other surface:
If you had filtered by name instead, each of these would have matched a different subset and you would have silently dropped half the data — without any endpoint returning an error.
Tone and share of voice are the two people find last and use most. Tone is scored by us across news coverage, per entity per story per day — so it moves with what is actually being published, not with a sentiment model run over a headline. Share of voice puts that in context against a peer set: a tone drop matters differently when your coverage volume tripled the same week.An absent bucket means no measured coverage, never a neutral reading. See Media Intelligence in the reference for the full surface.

​
Doing the same thing through MCP

Same four steps, no HTTP. Point an agent at the MCP server and it discovers the tools itself:
Use REST when you are writing a service; use MCP when a model is deciding what to call next. The data and the gating are identical — the MCP routes to the same serve functions.

​
Four things worth knowing before you build

Not to all of history. Other families carry their own default, declared on each days parameter in the API reference. Pass days or an explicit date_start/date_end window whenever the window matters to your answer. Windows are bounded — an unbounded scan across the whole corpus is refused rather than served slowly.
It echoes what the server actually applied, using canonical names whatever spelling you sent. If a strict endpoint does not recognize a parameter, the request fails with 400 UNKNOWN_PARAM. On an endpoint still using the compatibility contract, the request may succeed but list that parameter in applied_filters.ignored. In either case, correct the request before using the returned data.
A null metric means the observable was not found. A 0 means it was found and measured as zero. Charting null as 0 will invent a trend that is not there.
List endpoints return a cursor. Offset pagination drifts as new rows land mid-walk; the cursor does not.

​
Next

Recipes

Short copy-paste queries for the common shapes.

API reference

Every endpoint, parameter and value.