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

# Event Metrics

> Four rubric scores on every CAMEO+ event — what they mean, how each is computed, and what they do not claim.

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

<Info>
  **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.
</Info>

| Field                                                     | Question it answers                                       | Range                   |
| --------------------------------------------------------- | --------------------------------------------------------- | ----------------------- |
| [`magnitude`](/metrics/magnitude)                         | How intense was this event, for its own type?             | 0–10, null when unknown |
| [`systemic_importance`](/metrics/systemic-importance)     | How much does the wider system depend on what it touched? | 0–1                     |
| [`propagation_potential`](/metrics/propagation-potential) | How open are the routes out of it, right now?             | 0–1                     |
| [`market_sensitivity`](/metrics/market-sensitivity)       | How directly does it attach to something actually traded? | 0–1                     |

## Before you use them

<Warning>
  Read [**Limits and error bars**](/metrics/limits) 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.
</Warning>

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

```bash theme={null}
curl -H "Authorization: Bearer $GDELT_API_KEY" \
  "https://gdeltcloud.com/api/v2/events?limit=1"
```

```json theme={null}
{
  "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.