This page is about what the nouns MEAN. Response shapes are in the
OpenAPI schemas; the values each filter accepts are in
Reference.
The six nouns
Article → Story → Event is the spine
An article is evidence. A story is the deduplicated development several articles describe. An event is the structured claim we are willing to stand behind, coded into a taxonomy with a date, a place, actors and metrics. The distinction matters for counting. Three publishers covering one strike is one story and one event, not three — which is the whole reason the pipeline exists, and it is why an article-count and an event-count answer different questions. It runs the other way too: one story can produce several events. A single cluster covering a border incident may yield an armed clash, a diplomatic protest and an airspace closure — three distinct coded claims, each with its own actors, date and metrics, all citing the same coverage. So stories and events are not two views of the same list, and neither count is a proxy for the other. Ask for events when you want incidents; ask for stories when you want narratives. Some events come from a company’s own SEC 8-K filing: a cyber incident, a CEO change, a plan to exit a business or cut jobs, a bankruptcy, or a merger agreement. Such an event has no linked story:story_refs is empty, and its source and top article are the filing on sec.gov. It is merged with news
events of the same incident when matched.
Events come in two families
The family is decided by a single test: did it happen, or was it said?- Conflict (ACLED-compatible categories, coded by GDELT Cloud) — a discrete act of political violence, armed conflict, protest, riot or explosion that occurred.
- CAMEO+ — every speech act (a threat, demand, agreement, sanction) and every non-violent event across the other CAMEO+ domains.
Conventions every endpoint shares
One identity, everywhere
Resolve candidates once, select the intended identity, and reuse its returned ID in each destination endpoint’s documentedentity parameter. Accepted identifier spaces differ by
endpoint: reporting supports spine and news identities, while some source-specific legs require
particular identifiers. Check the identifier parameter contracts
before chaining calls; an unsupported or unlinked identity must not become a claim of zero records.
Finding an entity by name
Start at the unified search endpoint, then reuse the id it hands back:sources availability map and its cross-source identifiers. Use type
to narrow an ambiguous name to a person, organization, place or facility; clients should present weak or
ambiguous candidates rather than selecting one automatically.
Select an entity candidate, then reuse its returned ID in the destination endpoint’s documented
entity= parameter. Facilities return facility_id, separate from an owner entity or nearby
Events. Unlinked source records retain their source key and a null entity ID.
When you know the country, send it with country_match=strict to keep only candidates with known
evidence for it; without a country, region or continent, strict changes nothing. Inspect
country_evidence: office country, legal registration, citizenship and reporting geography are
different relationships. country_match=include_unknown, which is also what you get by omitting the
parameter, keeps candidates with no country evidence as well. Politicians remain people selected through
holds_office=true and published office evidence.
The reporting directory /api/v2/entities answers which entities appear in a selected reporting
window. Initial identity lookup uses /api/v2/search. Source and facility access remains subject
to the existing account entitlements; withheld source keys are omitted and failed coverage is unknown.
Entity Monitors take a resolved entity id rather than a bare name, and accept every id-space
/api/v2/search returns — a spine id (e_…), a news id (wiki:…) or an extracted-identity id
(llm:…). Pass whichever the resolver gave you; the monitorable boolean on each search
result says outright whether that exact id is accepted as a Monitor subject. Holding out for an
e_… id is the one thing to avoid: six of the twenty most-covered organizations — TikTok, the
Pentagon, the Senate, the Supreme Court, ICE and North Korea — have no e_ id at all, and an
e_-only rule made them unwatchable. A
scheduled question must not silently change subjects when name rankings change. Their public v1
match mode is coverage: mention and linked-Story evidence, not a claim of material involvement or
actor attribution.
Some endpoints take a name directly and resolve it for you; those that require an id return
400 INVALID_ENTITY_ID for a bare name. Either way this endpoint is how you get the id. Older
material referring to /api/v2/entities/resolve is wrong — no such endpoint exists.applied_filters tells you what actually happened
Every successful response echoes the filters the server applied. Descriptor-backed endpoints reject
an undeclared parameter with 400 UNKNOWN_PARAM and include details.did_you_mean plus the accepted
parameter names. Endpoints still being migrated may instead return it under
applied_filters.ignored; a non-empty ignored object means those parameters did not affect the rows.
Older spellings of some parameters still work.
Older parameter names gives the name to send instead.
NULL means unknown; it is never a fabricated 0
A missing observable is UNKNOWN. A 0 asserts a measurement somebody made. This applies to metrics,
to coverage counts, and to every derived number the API serves — and it is the reason some fields
come back null rather than helpfully zeroed.
Date windows are bounded
Windows are capped (30 days on most endpoints) anddays or date_start + date_end are
resolved together. Bounds and defaults per endpoint are in
Parameter reference.
Search is not one thing
Some endpoints run semantic search — the string is embedded and ranked by cosine similarity, so results are conceptual neighbours. Others run a lexical match over named columns and keep their own default ordering, which means a query matching more rows thanlimit returns an
arbitrary slice. The per-parameter description says which, and it is worth reading before assuming
relevance ordering.
Coverage
Consistently coded history begins in March 2026 and runs to now. Every successful response states where coverage starts inmeta.coverage.start. A window that lies entirely before it returns
400 DATE_OUT_OF_COVERAGE; a window that begins before it is served from the covered part, and
meta.window_adjustment says so.
Coverage is not uniform, and the honest way to find out where it is thin is to ask rather than to
trust a number written here: GET /api/v2/intelligence/coverage reports what can and cannot be
read, per place and period. Per-dataset windows, cadences and known gaps are in the
data catalog, which is generated from the same records the public data page uses.
The general shape: world and continent readings are well supported, country readings much less so,
and any single day in a low-coverage place should be treated as a sample rather than a census.
How fresh is it
New Events and Stories arrive throughout the day, and recent days keep filling for a while after they end, because reporting about an event can arrive after the event. To compare periods, use windows the response reports as complete. Every Events and Stories response says what it covers:
To keep your own copy current, see Keep a copy in sync.
Where the values live
When you need a value list — a category, a code, a country format, an id space — do not guess and do not hardcode from an example. Every vocabulary the API validates against is published, and each is labelled with whether the list is exhaustive:
The distinction that matters most is on How to read the reference: a vocabulary
is closed (a fixed list — safe to switch on), observed (what the corpus currently holds —
never treat as exhaustive), or an identifier (discovered through a call, never enumerated).
Treating an observed list as closed is the single most common way to build a filter that silently
misses data.
Monitors are standing API questions
A Monitor stores one Event/Story question, evaluates it on an hourly or daily half-open window, and retains triggered runs for seven days. It uses the same serving functions as the Core API. Scheduled evaluation costs 0 QU; an accepted on-demand Preview costs 1 QU and returns representative rows for inspection without saving or delivering anything. Run counts and inline samples are different.result_count is the execution’s reported count,
retained_row_count is how many execution rows were stored, and the canonical matches array holds
at most ten cards. When semantic retrieval reaches its candidate ceiling,
total_matches_is_lower_bound is true and candidate_limit names that ceiling. See
Monitors for the complete workflow and exact replay rules.
Next
Quickstart
Make your first call.
Endpoint index
See the whole surface at once.
Event metrics
What the numbers mean.
How events are coded
The pipeline behind an event.
Conflicting candidate types
Candidate search preserves unresolved disagreement between linked source records. Such a candidate returnsentity_type: "entity" with type_evidence.status: "conflicting", the possible types, and each supporting record’s ID, source, and raw type. A type filter may include the candidate when that type is a published possibility; it does not resolve the disagreement. Select the stable identity explicitly and inspect the evidence before treating it as a person or organization. Politician filtering also requires published office evidence.
A registry country association can describe the source relationship. For example, an SEC-seeded USA association means SEC filing association; it does not establish the issuer’s headquarters, domicile or citizenship. Candidate country_evidence states this basis when available. Unknown association remains unknown, and strict country matching never guesses a country from an entity’s name.
