> ## 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.

# GDELT Cloud

> A clean event database over the world's news — events, stories, entities, tone — by REST and MCP.

We read the world's news and produce a structured event database from it: **events** coded into a
taxonomy, **stories** clustered from the articles behind them, **entities** resolved to a single
identity across every surface, and **tone** scored on how each of them is covered.

Query it over REST, or point an agent at the MCP server.

```python theme={null}
import os, requests

r = requests.get(
    "https://gdeltcloud.com/api/v2/events",
    headers={"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"},
    params={"country": "Nigeria", "days": 7, "limit": 5},
)
for e in r.json()["data"]:
    print(e["event_date"], e["category"], "—", e["title"])
```

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    A working call in two minutes, plus the docs MCP server.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference">
    Every endpoint, parameter and value.
  </Card>
</CardGroup>

## What you can ask it

|                                     |                                                                                            |
| ----------------------------------- | ------------------------------------------------------------------------------------------ |
| **What happened**                   | `/events` — coded incidents with actors, geography, taxonomy and metrics                   |
| **What is being said**              | `/stories` — article clusters with the source coverage behind them                         |
| **How much, where, trending how**   | `/events/summary`, `/stories/summary` — counts grouped by date, place or category          |
| **Who is involved**                 | `/search` then `/entities` — resolve a name once, reuse the id everywhere                  |
| **How they are being covered**      | `/entities/{id}/tone`, `/share-of-voice` — press tone and coverage share over time         |
| **What they own or are exposed to** | `/facilities`, `/gov/awards`, `/filings`, `/exposure` — the same entity id, other surfaces |

## The one idea worth knowing

**Resolve a name to an id once, then never resolve it again.** Every surface above takes the same
`entity` id, so one call to `/search` joins news, tone, awards, filings, physical assets and
ownership exposure. Filtering by name string instead silently matches a different subset on each —
with no endpoint returning an error.

<Card title="Track an entity across every surface" icon="code" href="/guides/for-developers">
  Resolve a name to an id once, then reuse that id on news, tone, awards and physical assets.
</Card>

## What is ours and what we ingest

**Core** is what we produce — events, stories, entities, tone. We code every event under our own
taxonomy from the raw article stream; we do not resell anyone's event data.

**Open Feeds** are public registries we ingest and resolve onto the same entity spine — SEC filings,
GLEIF, USAspending, FRED, Global Energy Monitor, Epoch AI and more. The value we add is the fusion.

<Card title="Data catalog" icon="database" href="/data/catalog">
  Every dataset, its licence, its coverage window, and what it does not cover.
</Card>

<Info>
  Consistently coded history begins in **March 2026**. Earlier dates return a near-empty result that
  reads like a bug and is not — history is being extended backwards.
</Info>