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

# API v2

> Clean Events, Stories, Entities, Energy Data, and geo discovery endpoints for generated GDELT Cloud data.

API v2 is the simplified, recommended interface for generated GDELT Cloud products — clean structured
Events, clustered Stories, resolved Entities, energy assets, and geo discovery. v1 remains available for
existing integrations (see **Legacy v1 API** at the bottom of the sidebar).

v2 focuses on:

* Generated structured Events: `conflict` and `cameoplus`.
* Generated clustered Stories.
* Generated metrics for Events and Stories.
* Entity discovery and entity-to-Story/Event linking.
* Entity Tone and Share of Voice beta analytics for cached, evidence-gated media-tone workflows.
* Global Energy Monitor energy asset and owner search, summaries, maps, and detail records.

<Info>
  v2 does not expose raw GDELT-only fields or legacy tuning knobs such as `scope`, `detail`,
  `geo_scope`, `event_readiness`, `cluster_certainty`, `quad_class`, or raw `total_events`.
</Info>

## Start here

<CardGroup cols={3}>
  <Card title="Concepts & Response Objects" icon="diagram-project" href="/api-reference/concepts">
    Auth, geography & bounding boxes, the Event/Story/summary response schemas, entity resolution, and ranking.
  </Card>

  <Card title="Taxonomy & Codes" icon="list-tree" href="/api-reference/taxonomy">
    Every controlled value: event families, CAMEO+ domains and codes, Conflict types, story categories, and filter enums.
  </Card>

  <Card title="Cookbook" icon="book-sparkles" href="/api-reference/cookbook">
    Field-tested query recipes — monitoring, semantic search, summaries, and drilldowns.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get an API key and make your first authenticated call.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Bearer `gdelt_sk_…` keys, plans, and access.
  </Card>

  <Card title="MCP server" icon="plug" href="/mcp/introduction">
    The same data as agent-callable tools over the Model Context Protocol.
  </Card>
</CardGroup>

## Endpoints in the sidebar

Browse the live, interactive endpoint reference in the sidebar — each page has a parameter reference,
response schema, and an in-browser playground:

* **Events** — search, fetch, and summarize generated structured Events.
* **Stories** — search, fetch, list articles, and summarize clustered Stories.
* **Entities** — discover people and organizations and resolve names to canonical ids.
* **Unified search** — `/api/v2/search` finds an entity by any name or alias across every universe (news, GEG-Wikipedia, SEC, GEM, screening lists, China dev-finance, Epoch AI) and returns the id the other endpoints take. Open to any authenticated key.
* **Geography** — country-scoped admin1 discovery.
* **Energy** — Global Energy Monitor asset and owner search, summaries, maps, and detail.
* **Facilities** — the unified physical-asset directory (GEM assets + WPI ports + Epoch AI data centers), resolved to spine owners (plan-gated, Analyst+).
* **Filings** — SEC EDGAR filings, XBRL financials, and AI-extracted relations (plan-gated: the Corporate & Supply Chain plan and above, `can_use_filings`).
* **Media Intelligence** — Entity Tone (`can_use_tone`) and Share of Voice (`can_use_share_of_voice`); social signal remains an admin-only preview.
* **Risk & Screening** — restricted-party list catalog, entries, and change feed plus counterparty screening (`can_use_screening`), and ownership-chain exposure (`can_use_exposure`).
* **China** — China overseas development-finance projects and rollups, AidData GCDF (`can_use_china`).
* **Government** — federal awards and FARA foreign-influence links (`can_use_gov`).
* **Maritime & Trade** — chokepoint transits, dwell episodes, AIS-dark gaps, vessels and carriers, ports, port pulse, and chokepoint watch (`can_use_maritime`).
* **Markets & Macro** — FRED economic series, point-in-time (ALFRED) observations, and releases (`can_use_macro`).
* **AI & Compute** — Epoch AI models, hardware, data centers, companies, and chip sales (`can_use_epoch_ai`).
* **Briefs** — generate source-backed Monitoring Briefs (plan-gated add-on).

Events and Stories accept a **`languages`** filter — a comma-separated list of source-language codes
(`en`, `zh`, `ar`, `es`, `fr`, …) that keeps only items whose linked story has at least one article in
those origin (source) languages; multiple codes are OR'd and the alias `language` is accepted. The Events
and Stories **list** endpoints also accept **`include_images`** (default `true`) to add best-effort
representative article image URLs per row (`image_url` plus `top_articles[].image_url`).

Media Intelligence, Risk & Screening, China, Government, Maritime & Trade, Markets & Macro, and AI &
Compute are **generally available and plan-gated** — if your plan carries the source flag, your key gets
the same data these pages demo. A plan without the flag gets a `403 PLAN_REQUIRED` naming the missing
entitlement, never a silently empty result. Only `/api/v2/social` (social signal) is still an admin-only
internal preview.

## Authentication

Every request uses a Bearer API key — see [Concepts → Authentication](/api-reference/concepts#authentication):

```bash theme={null}
Authorization: Bearer gdelt_sk_...
```

## Entity Tone & Share of Voice (beta)

Entity Tone is an opt-in, evidence-gated beta surface for media tone toward a resolved entity — not
polling data or a direct measure of public opinion. Missing tone rows mean `not_available` or
`insufficient_entity_evidence`, **not** neutral. Evidence is drawn from clustered news plus supplementary
social signal (Bluesky / AT Protocol) where available, with a news-vs-social split so you can see how
press-driven a read is. `tone_score` is returned on a `-100..100` scale; `risk_score` on `0..100`.

Share of Voice is denominator-explicit: `/api/v2/share-of-voice` requires `entities`, `start_date`,
`end_date`, and at least one denominator-defining filter (`query`, `topic`, `category`, `country`,
`region`, `languages`, or `source_set`). Requests without a denominator return `DENOMINATOR_REQUIRED` so
callers cannot report a percentage without a defined media space. `topic` is the literal story-label
denominator (the exact label bounds the media space); `query` is the semantic, embedding-based denominator
(opt-in and slower — it defines the media space by similarity rather than a literal label). Responses include a plot-ready
`timeline` with zero-filled buckets and per-point `story_share`, `article_share`, `weighted_share`, and
`delta_from_previous_bucket`. Add `include_tone=true` to join cached tone aggregates, `languages` (e.g.
`ar,zh,en`) to compare coverage across language spheres, and `include_drivers=true` for citable
per-bucket drilldowns.

<Note>
  Entity Tone and Share of Voice are **beta** — methodology and response shape may still change — but they
  are generally available, not admin-only. Entity Tone requires `can_use_tone` (the Analyst, Media
  Intelligence, Geopolitical Intelligence, and Global Intelligence plans); Share of Voice requires
  `can_use_share_of_voice` (Media Intelligence, Geopolitical Intelligence, and Global Intelligence). Find
  them under **Media Intelligence** in the sidebar.
</Note>