# GDELT Coverage Timeline

> GDELT Coverage Timeline is a paid API for AI agents from payai.agentstools.dev, paid per call via x402, $0.006/call, status unknown (last checked 2026-09-16).

Returns a normalized time-series of media coverage volume or tone for a topic, theme, or country from the GDELT Project, plus latest value and trend direction.

## Facts

- Endpoint: GET https://payai.agentstools.dev/gdelt/timeline
- Price: $0.006/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-16
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/gdelt-coverage-timeline-a030ecb7
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_a26RVssF53SafmFmnHOL4

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability gdelt-coverage-timeline-a030ecb7
```

Example prompt: Can you pull the GDELT coverage volume timeline for 'artificial intelligence' over the past week and tell me whether it's rising or falling?

## When to prefer this

Use this endpoint when you need a time-series trend of news media coverage — either volume share or sentiment tone — for a specific topic, geopolitical theme, or country over a defined lookback window. It is ideal for monitoring whether a topic is heating up or cooling down in global media, or tracking tone shifts. Prefer it over static news aggregators when trend direction and temporal shape matter more than individual headlines.

## Known failure modes

- Missing both query and theme/country — at least one must be provided
- Invalid or unsupported timespan format returns an error
- Unknown country or language name not recognized by server-side mapping
- GDELT upstream service unavailable or rate-limited
- Empty results if no matching coverage exists in the selected timespan

## How this service works

Coverage timeline for a topic from the GDELT Project: pick metric volume (share of all monitored coverage — is a topic heating up or cooling down) or tone (average-tone trend). Returns normalized time-series points plus the latest value and a rising/falling/flat trend. One upstream call.

## Output

Returns a normalized time-series array of data points (timestamps + metric values), the latest metric value, and a trend label (rising, falling, or flat). The metric is either coverage volume (share of all monitored media) or average tone for the queried topic/theme/country.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [],
     "properties": {
      "lang": {
       "type": "string",
       "description": "Source-language filter by name (english, russian, arabic, ...)."
      },
      "query": {
       "type": "string",
       "description": "Free-text topic (multi-word phrases are auto-quoted). Optional if a theme/country is given."
      },
      "theme": {
       "enum": [
        "protests",
        "terrorism",
        "conflict",
        "war",
        "inflation",
        "sanctions",
        "trade",
        "elections",
        "corruption",
        "cyber",
        "immigration",
        "refugees",
        "climate",
        "disaster",
        "epidemic",
        "energy",
        "economy",
        "diplomacy",
        "coup",
        "unrest"
       ],
       "type": "string",
       "description": "Curated GDELT GKG theme filter (friendly name mapped to a GKG code)."
      },
      "metric": {
       "enum": [
        "volume",
        "tone"
       ],
       "type": "string",
       "description": "volume = coverage share over time; tone = avg-tone trend."
      },
      "country": {
       "type": "string",
       "description": "Source-country filter by friendly name (United States, Russia, China, ...); mapped to the GDELT FIPS 10-4 code server-side."
      },
      "timespan": {
       "type": "string",
       "description": "Lookback window: 15min, 24h, 3d, 1w, 1m (default 24h)."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/gdelt-coverage-timeline-a030ecb7/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from payai.agentstools.dev](https://www.zero.xyz/host/payai.agentstools.dev/llms.txt)