Get GDELT Coverage Timeline
gdelt_get_coverage_timelineRetrieve 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 "volume_raw" for distinct matching-article counts per timestep and norm, the unsmoothed monitored-article denominator; smoothed counts are moving averages. 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 each timestep carries its first 3 article links and referenceCount, the number of references GDELT supplied (up to ten), not all matching articles; name timesteps' dates in points to get only those timesteps, each with its full supplied list. A response carries limit timesteps (default 10, cap 400); when more remain it returns nextOffset — pass it back as offset with otherwise identical inputs for the next page. Explicit startDatetime/endDatetime windows may predate the last 3 months in "volume" and "tone" modes; "volume_raw" and "volume_with_articles" cover only the last 3 months.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "gdelt_get_coverage_timeline"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Timeline mode: "volume" returns normalized coverage % per timestep, "volume_raw" returns distinct matching-article counts (moving averages when smoothed) and the unsmoothed monitored denominator norm, "volume_with_articles" returns volume plus top articles per spike (best for signal detection), "tone" returns average sentiment score per timestep. | volume |
| limit | No | Maximum timesteps per page (default 10, cap 400). Larger counts clamp with limitClamp; strict deployments reject them. | |
| 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<. | |
| offset | No | Zero-based timestep offset — into the timeline, or into the timesteps named in points. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page. | |
| points | No | Timestep dates to return alone, 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. The response then carries only these timesteps, in timeline order, and in volume_with_articles mode each carries its complete article list instead of the first 3. 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 | Trailing moving-average width in timesteps (0–30; 0 or 1 leaves values unsmoothed). Width N needs N source steps, omitting leading steps without a full window and potentially shifting peaks later. | |
| 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. In "volume" and "tone" modes the window may predate the last 3 months; "volume_raw" and "volume_with_articles" cover only the last 3 months. | |
| 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. In "volume" and "tone" modes the window may predate the last 3 months; "volume_raw" and "volume_with_articles" cover only the last 3 months. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 — or, when this response is one page of several, which timesteps it returned out of how many. When the server's local GKG mirror answered (source: gkg_mirror), why, and how its figures differ from the DOC API's. Absent when the DOC API answered and the whole timeline fit in one response. | |
| series | No | One or more time series (typically one for volume/tone), holding the timesteps of this page. | |
| source | No | Where this answer came from: doc_api, the GDELT DOC API, or gkg_mirror, the server's local mirror of GDELT's Global Knowledge Graph, which answers when the DOC API refuses the request or returns nothing. Present on every answer while the server runs a mirror; absent otherwise. | |
| attempts | No | Each source tried for this call, in order. Present only when the DOC API did not answer with data and the mirror was consulted. | |
| coverage | No | Present only when the mirror answered less than the requested window. Every count, share, and article in this response comes from answeredStart through answeredEnd; nothing outside it, or in a missing slot, was counted. | |
| limitClamp | No | Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value. | |
| nextOffset | No | Offset of the next page, for the same inputs. Absent when this page reaches the last timestep. | |
| totalCount | No | Total number of data points across all series of the full timeline, not this page. | |
| endDatetime | No | Echoed end datetime when provided (YYYYMMDDHHMMSS). | |
| staleResponse | No | Present only when the refetch of this exact request was refused, failed, or came back empty, and the response is GDELT's stored answer from fetchedAt instead. It holds nothing published after fetchedAt; a relative timespan covers the window ending at fetchedAt, not now. Absent on a live answer. | |
| 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 this response is restricted to, each carrying its full article list — echoing the points input. Omitted when points was not supplied. |