gdelt-mcp-server

Get GDELT Coverage Timeline

gdelt_get_coverage_timeline

Read-only

Retrieve a time series showing when news coverage of a topic spiked, or how average tone shifted over time. Use mode "volume" for normalized coverage intensity (% of all global coverage per timestep). Use mode "volume_with_articles" for the same signal plus the top articles that drove each spike — this is the primary signal-detection mode: a single call reveals both the spike and its cause, avoiding a follow-up gdelt_search_articles call. Use mode "tone" for average sentiment score per timestep (negative = hostile/fearful, positive = celebratory). Date resolution is inferred from returned intervals: 15 minutes or hours for short windows, days for longer ones. In volume_with_articles mode the text surface shows the first 3 article links per timestep next to that timestep's true article count; name a timestep's date in points to render its full list. Note: DOC API covers only the last 3 months.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	Timeline mode: "volume" returns normalized coverage % per timestep, "volume_with_articles" returns volume plus top articles per spike (best for signal detection), "tone" returns average sentiment score per timestep.	volume
`query`	Yes	Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes), tone<.
`points`	No	Timestep dates whose complete article list should be rendered in the text surface, e.g. ["2024-01-05T12:00:00Z"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. Only affects volume_with_articles rendering — every timestep already carries its full article list in structuredContent regardless. Timesteps not named here show their first 3 links; a date matching no timestep is rejected rather than silently ignored.
`timespan`	No	Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.
`smoothing`	No	Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics.
`endDatetime`	No	End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected.
`startDatetime`	No	Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected.

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	No	Timeline mode used for this response.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when timeline data was returned.
`series`	No	One or more time series (typically one for volume/tone, one per label for breakdowns).
`totalCount`	No	Total number of data points across all series.
`endDatetime`	No	Echoed end datetime when provided (YYYYMMDDHHMMSS).
`startDatetime`	No	Echoed start datetime when provided (YYYYMMDDHHMMSS).
`dateResolution`	No	Temporal resolution of the data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.
`expandedPoints`	No	Timestep dates whose full article list is rendered in the text surface instead of the first 3, echoing the points input. Omitted when points was not supplied. Purely a rendering concern — structuredContent carries every article for every timestep either way.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 24, 2026

changedInput schema / properties / query / description

Previous value: -"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:, tone<."New value: +"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes), tone<."

Changed5 schema fields changedSep 24, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "dateResolution",
-      "series",
-      "effectiveQuery",
-      "mode",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "series",
+      "effectiveQuery",
+      "mode",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of the data points — 15min, hour, or day."New value: +"Temporal resolution of the data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_point`: A date passed in the points input matches no timestep in a non-empty timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_timeline_data",
-  "unknown_point",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "unknown_point",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no timeline data was returned. Absent on successful responses."New value: +"Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when timeline data was returned."

Changed1 schema field changedSep 22, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changed1 schema field changedSep 19, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changed2 schema fields changedAug 31, 2026

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of the data points — hour for short windows, day for longer."New value: +"Temporal resolution of the data points — 15min, hour, or day."

changedOutput schema / properties / dateResolution / enum

Previous value: -[
-  "hour",
-  "day"
-]New value: +[
+  "15min",
+  "hour",
+  "day"
+]

Changed3 schema fields changedAug 30, 2026

changedInput schema / properties / timespan / description

Previous value: -"Time window relative to now, e.g. \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."New value: +"Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_timeline_data",
-  "unknown_point",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_timeline_data",
+  "unknown_point",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changed6 schema fields changedAug 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dateResolution",
+      "series",
+      "effectiveQuery",
+      "mode",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_timeline_data",
+            "unknown_point",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "dateResolution",
-  "series",
-  "effectiveQuery",
-  "mode",
-  "totalCount"
-]

Changed2 schema fields changedJul 16, 2026

addedInput schema / properties / points

Added value: +{
+  "description": "Timestep dates whose complete article list should be rendered in the text surface, e.g. [\"2024-01-05T12:00:00Z\"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. Only affects volume_with_articles rendering — every timestep already carries its full article list in structuredContent regardless. Timesteps not named here show their first 3 links; a date matching no timestep is rejected rather than silently ignored.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / expandedPoints

Added value: +{
+  "description": "Timestep dates whose full article list is rendered in the text surface instead of the first 3, echoing the points input. Omitted when points was not supplied. Purely a rendering concern — structuredContent carries every article for every timestep either way.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed4 schema fields changedJul 16, 2026

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

Changed2 schema fields changedJun 8, 2026

addedOutput schema / properties / endDatetime

Added value: +{
+  "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

addedOutput schema / properties / startDatetime

Added value: +{
+  "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

Changed6 schema fields changedMay 30, 2026

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

changedOutput schema / properties / mode / description

Previous value: -"Timeline mode used."New value: +"Timeline mode used for this response."

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no data was returned. Absent on successful responses."New value: +"Recovery hint when no timeline data was returned. Absent on successful responses."

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total number of data points across all series.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "mode",
-  "dateResolution",
-  "series"
-]New value: +[
+  "dateResolution",
+  "series",
+  "effectiveQuery",
+  "mode",
+  "totalCount"
+]

First observedMay 29, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses rich behavioral details: date resolution is inferred from intervals, the text surface shows first 3 article links per timestep, named points render full lists, unmatched dates are rejected, and DOC API coverage is limited to 3 months. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph of ~150 words. Every clause adds operational value (mode semantics, resolution inference, rendering behavior, limitation), but it is longer than a minimal definition. It remains scannable and free of filler, so it earns a 4 rather than a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with an output schema and several siblings, the description covers the main decision axes: which mode to choose, how timestep granularity is determined, how to reveal full article lists, and the DOC API time window. The output schema handles return structure, so no further return-value detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 7 parameters already carry detailed schema descriptions (100% coverage), so the baseline is 3. The description adds cross-parameter context—how mode changes the signal returned, how points affects rendering, and the 3-month limitation—so it earns a 4. It does not repeat field-level explanations already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair ('Retrieve a time series') and then defines the three modes and what each returns. It explicitly contrasts with gdelt_search_articles, making the tool's role distinct from siblings like gdelt_get_coverage_breakdown or gdelt_get_tone_distribution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description maps each mode to a concrete use case ('primary signal-detection mode', 'normalized coverage intensity', 'average sentiment score') and recommends volume_with_articles to avoid a follow-up search. It does not explicitly state when to prefer this tool over the breakdown/tone-distribution siblings, but the mode guidance is strong and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All gdelt-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Get GDELT Coverage Timeline

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources