Docs menu

GDELT API endpoint

GDELT Timeline API

Returns how coverage of the required GDELT `query` changes over time, as dated points. `metric` picks `volume` (the default, share of monitored articles), `volume_raw` (matching article count), `tone` (average sentiment), or `lang` and `country` for one series per language or country. Filter with `country`, `language`, `domain`, `timespan` or `from` and `to`; `smooth` runs 0 to 30 (default 0).

GETapiKey0 credits/requestGDELTgdelt.timelineResponseDoc/gdelt/timeline

Endpoint facts

Method: GET
API path: /gdelt/timeline
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.timelineResponseDoc

GDELT News Monitoring API Try GDELT Timeline API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. Same syntax as gdelt-search's query.
metric (optional, default volume) — timeline metric. Allowed values: volume (coverage as a percentage of all monitored articles), volume_raw (the actual matching article count), tone (average sentiment, negative to positive), lang (coverage volume broken down by source language — one series per language instead of one aggregate series), country (coverage volume broken down by source country — one series per country instead of one aggregate series).
country (optional) — convenience source-country filter, appended to the query as sourcecountry:VALUE.
language (optional) — convenience source-language filter, appended to the query as sourcelang:VALUE.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
timespan (optional) — relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to (optional) — end of an absolute time window. Same formats as from.
smooth (optional, default 0) — moving-window smoothing applied to the timeline, in steps, 0-30. 0 disables smoothing.

Notable response behavior:

series contains exactly one entry for metric=volume/volume_raw/ tone; for metric=lang/country it contains one entry per language/country GDELT found in the matching coverage. Each entry's points is chronologically ordered.
source_url is the exact upstream GDELT DOC API URL used for the call.
A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/timeline?metric=volume&query=climate&timespan=1w
Items in series: 1
Fields filled in every checked item: 2

Field	Filled in, of 1 checked	Values in the sample
series	1
points	1	median 2 entries

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. Same syntax as gdelt-search's query.	climate change
metric	string	No	Timeline metric. lang and country return one series per language/country instead of one aggregate series. Allowed values: volume, volume_raw, tone, lang, country.
country	string	No	Convenience source-country filter, appended to the query as sourcecountry:VALUE.	unitedkingdom
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE.	english
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.	1w
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
smooth	integer	No	Moving-window smoothing applied to the timeline, in steps. 0 disables smoothing. Minimum: 0. Maximum: 30.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/timeline?query=climate+change&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "climate change",
    "metric": "volume",
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=timelinevol&query=climate+change",
    "fetched_at": "2026-08-20T10:00:00Z",
    "series": [
      {
        "series": "climate change",
        "points": [
          {
            "date": "2026-08-13T00:00:00Z",
            "value": 0.42
          },
          {
            "date": "2026-08-14T00:00:00Z",
            "value": 0.51
          }
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.timelineResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TimelineResponse	No
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.metric	string	No	volume
data.query	string	No	climate change
data.series	array	No
data.series[].points	array	No
data.series[].points[].date	string	No	2026-08-19T00:00:00Z
data.series[].points[].value	number	No	1.42
data.series[].series	string	No	climate change
data.source_url	string	No	https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=timelinevol&query=climate+change
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/timeline?query=climate+change&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More GDELT endpoint docs GDELT News Monitoring API GDELT Context Search API documentation GDELT Search API documentation GDELT Tone Chart API documentation GDELT Television Concept Entities API documentation GDELT Television Search API documentation GDELT Television Show Chart API documentation

Open in Playground Back to group

Docs menu

GDELT API endpoint

GDELT Timeline API

GETapiKey0 credits/requestGDELTgdelt.timelineResponseDoc/gdelt/timeline

Endpoint facts

Method: GET
API path: /gdelt/timeline
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.timelineResponseDoc

GDELT News Monitoring API Try GDELT Timeline API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. Same syntax as gdelt-search's query.
metric (optional, default volume) — timeline metric. Allowed values: volume (coverage as a percentage of all monitored articles), volume_raw (the actual matching article count), tone (average sentiment, negative to positive), lang (coverage volume broken down by source language — one series per language instead of one aggregate series), country (coverage volume broken down by source country — one series per country instead of one aggregate series).
country (optional) — convenience source-country filter, appended to the query as sourcecountry:VALUE.
language (optional) — convenience source-language filter, appended to the query as sourcelang:VALUE.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
timespan (optional) — relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to (optional) — end of an absolute time window. Same formats as from.
smooth (optional, default 0) — moving-window smoothing applied to the timeline, in steps, 0-30. 0 disables smoothing.

Notable response behavior:

series contains exactly one entry for metric=volume/volume_raw/ tone; for metric=lang/country it contains one entry per language/country GDELT found in the matching coverage. Each entry's points is chronologically ordered.
source_url is the exact upstream GDELT DOC API URL used for the call.
A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/timeline?metric=volume&query=climate&timespan=1w
Items in series: 1
Fields filled in every checked item: 2

Field	Filled in, of 1 checked	Values in the sample
series	1
points	1	median 2 entries

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. Same syntax as gdelt-search's query.	climate change
metric	string	No	Timeline metric. lang and country return one series per language/country instead of one aggregate series. Allowed values: volume, volume_raw, tone, lang, country.
country	string	No	Convenience source-country filter, appended to the query as sourcecountry:VALUE.	unitedkingdom
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE.	english
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.	1w
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
smooth	integer	No	Moving-window smoothing applied to the timeline, in steps. 0 disables smoothing. Minimum: 0. Maximum: 30.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/timeline?query=climate+change&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "climate change",
    "metric": "volume",
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=timelinevol&query=climate+change",
    "fetched_at": "2026-08-20T10:00:00Z",
    "series": [
      {
        "series": "climate change",
        "points": [
          {
            "date": "2026-08-13T00:00:00Z",
            "value": 0.42
          },
          {
            "date": "2026-08-14T00:00:00Z",
            "value": 0.51
          }
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.timelineResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TimelineResponse	No
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.metric	string	No	volume
data.query	string	No	climate change
data.series	array	No
data.series[].points	array	No
data.series[].points[].date	string	No	2026-08-19T00:00:00Z
data.series[].points[].value	number	No	1.42
data.series[].series	string	No	climate change
data.source_url	string	No	https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=timelinevol&query=climate+change
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/timeline?query=climate+change&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

GDELT Timeline API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

GDELT Timeline API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related