> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Concepts
> The six nouns the whole API is built from, and the conventions every endpoint shares.
Six nouns carry the entire product. Learn them once and every endpoint reads the same way.
This page is about what the nouns MEAN. Response shapes are in the
[OpenAPI schemas](/api-reference); the values each filter accepts are in
[Reference](/reference/index).
## The six nouns
| Noun | What it is | Where it comes from |
| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Article** | One news item from one publisher. | Ingested from the public GDELT article stream and native sources. |
| **Story** | A cluster of articles covering the same real-world development. | Embedding retrieval, then an LLM adjudicates every candidate pair. |
| **Event** | One discrete, coded thing that happened or was said. | An LLM codes stories into the taxonomy. One story can yield several events. |
| **Entity** | A resolved person, organization or place, stable across sources. | Wikipedia-linked, then collapsed through a shared arbiter. |
| **Facility** | A physical asset — a plant, mine, port, pipeline or data centre. | Global Energy Monitor, world port index, Epoch AI. |
| **Metric** | A number scored onto an event by a published rubric. | See [Event metrics](/reference/metrics). |
### 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.
### Events come in two families
The family is decided by a single test: **did it happen, or was it said?**
* **Conflict (ACLED)** — 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 nine further domains.
So *"X bombed Y"* is Conflict; *"X threatened to bomb Y"* is CAMEO+ POLITICAL. A threat is a speech
act even when its subject is violence.
The complete tree is in [Complete event taxonomy](/reference/taxonomy-complete); what each
individual code **means** is in [Event code definitions](/reference/codes-conflict).
## Conventions every endpoint shares
### One identity, everywhere
An `entity` parameter accepts a spine id (`e_…`), a news id (`wiki:…`) or a plain name, and resolves
through the same arbiter on every endpoint. That is a contract, not a convenience: if `/events` and
`/gov/awards` disagreed about what an entity is, a caller chaining them would silently drop half
their data.
### Finding an entity by name
Start at the unified search endpoint, then reuse the id it hands back:
```http theme={null}
GET /api/v2/search?q=&universe=all
```
This is the fuzzy "find the entity" step — use it whenever you have a possibly misspelled,
abbreviated or reordered name rather than an id. It searches every entity universe at once (news,
plus the structured registry: GEM energy owners, SEC/EDGAR filers, screening-list entries, China
financiers) and returns ranked candidates, deduplicated across sources, each carrying a `sources`
availability map and its cross-source `identifiers`. Narrow the sweep with `universe` — the accepted
values are in [Value reference](/reference/enums#search_universe).
Resolve once, then fan out: the same id works on the event, entity, energy, facility, filings and
screening surfaces. Search itself is open to any authenticated key — it reveals only that an entity
exists and which sources carry it; the detail behind a gated source still needs that source's plan
flag.
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.
Whichever spelling you sent, `applied_filters` reports the **canonical** name. The alias table is in
[Parameter reference](/reference/parameters#aliases).
### `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) and `days` / `window` / `date_start` + `date_end` are
resolved together. Bounds and defaults per endpoint are in
[Parameter reference](/reference/parameters).
### 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** substring match over named columns and
keep their own default ordering, which means a query matching more rows than `limit` 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, refreshed through the day.
Earlier dates return a near-empty result that reads like a bug and is not — there is a thin tail of
back-dated article noise before that, not usable history, and the window is being extended backwards
over time.
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](/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
The pipeline runs continuously; nothing here is a nightly batch. Concretely:
| Layer | Cadence | What lands |
| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Articles → Stories → Events | **hourly** | New articles ingested, clustered into Stories, coded into Events. A development usually becomes a coded Event within a few hours of first publication. |
| Story reconciliation | hourly | Same-day duplicate Stories adjudicated and merged. |
| Coding catch-up | hourly | Stories the first pass could not code yet. |
| Daily snapshots | **every 30 min** | The pre-built partitions the API reads from. |
| Entity resolution | hourly, plus daily and weekly passes | New mentions resolved; the identity arbiter re-runs daily. |
| SEC filings | hourly | New EDGAR submissions. |
| Maritime, macro | hourly | Vessel positions, FRED series. |
| Screening lists, registries | daily to weekly | Sanctions and debarment lists, GLEIF, asset registries. |
Two consequences worth designing for:
* **Today is still moving.** A query for today returns fewer events than the same query tomorrow,
because coding is still in progress. That is not a gap; it is the current state. For stable
day-over-day comparisons, end your window yesterday.
* **`meta.settled_at` tells you when.** Every `/api/v2/events` response carries a `meta` block:
`row_source` says whether the rows came from a snapshot or were computed live, and `settled_at`
is when that snapshot was built. You never have to guess how fresh a number is.
## 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:
| You need | Go to |
| ------------------------------------------------ | -------------------------------------------------------------------- |
| Every filter value an endpoint validates | [Value reference](/reference/enums) |
| What a parameter accepts, its aliases and bounds | [Parameter reference](/reference/parameters) |
| What an event code **means** | [Event code definitions](/reference/codes-conflict) and its siblings |
| The full code tree | [Complete taxonomy](/reference/taxonomy-complete) |
| What a metric measures and does not claim | [Event metrics](/reference/metrics) |
| Per-dataset coverage, licence and cadence | [Data catalog](/data/catalog) |
| Error codes and what to do about each | [Errors](/reference/errors) |
The distinction that matters most is on [How to read the reference](/reference/index): 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.
## Next
Make your first call.
See the whole surface at once.
What the numbers mean.
The pipeline behind an event.