GDELT Cloud Docs — Global Event Data API & MCP

Every CAMEO+ event carries four scores. They are rubric judgements computed by published formulas, not measurements and not forecasts.

The model reads facts; a formula does the arithmetic. A language model reads the coverage for one event and extracts a small set of concrete sub-factors, recording why it chose each value. A fixed, versioned function then turns those facts into a score. This is the split canonical event datasets have always used — KEDS and TABARI through PETRARCH to ICEWS and GDELT — and it is what makes a score re-derivable by hand rather than an opaque model output.

Field	Question it answers	Range
`magnitude`	How intense was this event, for its own type?	0–10, null when unknown
`systemic_importance`	How much does the wider system depend on what it touched?	0–1
`propagation_potential`	How open are the routes out of it, right now?	0–1
`market_sensitivity`	How directly does it attach to something actually traded?	0–1

Before you use them

Read Limits and error bars before putting these in a model or an alert threshold. Three things matter most: they are CAMEO+ only (conflict events omit all four rather than return 0), coverage against hard registries is 2.2%, and each scale has a measured noise floor below which a difference means nothing.

Getting the evidence, not just the score

Events coded from 28 July 2026 return the sub-factors and the coder’s reason for each under metrics.metric_inputs. Older events omit the field — the evidence was not recorded for them, and a backfill is planned but has not run.

curl -H "Authorization: Bearer $GDELT_API_KEY" \
  "https://gdeltcloud.com/api/v2/events?limit=1"

{
  "metrics": {
    "magnitude": 7,
    "systemic_importance": 0.57,
    "propagation_potential": 0.42,
    "market_sensitivity": 0.8,
    "metric_inputs": {
      "magnitude": { "path": "economic", "value": 7, "why": "Final approval imposes a $1.5 billion copyright settlement…" },
      "market": {
        "claim_exposure": { "value": 0.8, "why": "Acts directly on the company's own legal and contractual claim…" },
        "economic_bite":  { "value": 0.8, "why": "Approval makes a large obligation operative…" }
      }
    }
  }
}

Versioning

Each event stamps metric_version. The current contract is v2-2026-07-24, in effect from 28 July 2026. Events coded earlier sit on the previous scale. metric_version is stored but not currently returned by the API, so use the presence of metrics.metric_inputs as the boundary marker — it appears only on v2 events.

Getting Started

Atlas

Data Methodology

Event Metrics

Workflow Guides

Developer Resources

Event Metrics

Before you use them

Getting the evidence, not just the score

Versioning

​Before you use them

​Getting the evidence, not just the score

​Versioning

Before you use them

Getting the evidence, not just the score

Versioning