Docs menu

GDELT API endpoint

GDELT Timeline API

Use Crawlora's GDELT Timeline API to extract supported public GDELT data as structured JSON. This page includes request parameters, cURL examples, response schema, error behavior, credit cost, and a Playground link for testing before integration.

GETapiKey0 credits/requestGDELTgdelt.timelineResponseDoc/gdelt/timeline

Endpoint facts

Method: GET
API path: /gdelt/timeline
Auth: apiKey
Credits: 0 credits/request
Platform: GDELT
Response schema: #/definitions/gdelt.timelineResponseDoc

Overview

Return how a query's global news coverage has trended over Developers commonly use this endpoint for data enrichment, monitoring, research dashboards, internal automation, and agent-native workflows that need repeatable structured public web data. Authentication uses the documented Crawlora headers, and usage is metered with the credit cost shown on this page.

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

Request parameters

Request parameters are generated from the active endpoint catalog. Required values must be sent before Crawlora can call the upstream public web data source.

Parameter	Type	Required	Description
query	string	Yes	GDELT query string. Same syntax as gdelt-search's query.
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.
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE.
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to	string	No	End of an absolute time window. Same formats as from.
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=coffee&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Authentication

Send your scraping API key in the x-api-key header. Use the console API Keys page to rotate or select the active key.

Billing

Endpoint usage is metered in credits. The plan prices, included credits, limits, and overage rates below match the active backend billing configuration.

Credit cost: 0 credits/request
Charged response: Successful 2xx responses

Plan	Price	Included credits	Daily cap	Rate limit	Overage
Free	$0/mo	2,000	500 daily credits	5/min	No overage
Starter	$9/mo	20,000	5,000 daily credits	15/min	$0.75/1,000 overage credits when enabled
Growth	$29/mo	100,000	25,000 daily credits	45/min	$0.45/1,000 overage credits when enabled
Pro	$79/mo	400,000	No daily cap	120/min	$0.30/1,000 overage credits
Business	$199/mo	1,200,000	No daily cap	300/min	$0.20/1,000 overage credits
Enterprise	$499/mo	5,000,000	No daily cap	1,000/min	$0.12/1,000 overage credits

Infrastructure behavior

This endpoint is executed through Crawlora's managed scraping infrastructure.

Proxy strategy: managed automatically where needed
Browser rendering: enabled for supported targets that require rendered HTML or JavaScript execution
Browser cluster: supported dynamic workloads can be routed through distributed browser instances
Retry behavior: automatic retry/fallback may be used depending on endpoint type
Challenge handling: challenged pages or unusable upstream HTML are detected and surfaced clearly when they cannot be used
Billing: credits are charged only for successful 2xx responses
Observability: responses include request context where available

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. Example response: ```json { "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 } ] } ] } } ```

Catalog quality warnings

missing example for required query param: query

Error behavior

Crawlora does not silently return bad data when the upstream page cannot be used.

Status	Common failure case
400	Invalid input or missing required parameter
429	Plan or endpoint rate limit exceeded
500	Internal execution error
502	Upstream platform failed, returned unusable HTML, or served a challenge page that could not be resolved

When possible, Crawlora returns structured error context so your integration can retry, back off, or inspect the request.

Failure responses

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

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

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=coffee&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Responsible public web data workflows

Crawlora is designed for responsible structured public web data workflows. Customers are responsible for using Crawlora in compliance with applicable laws, third-party rights, target-platform rules, and Crawlora terms.

Read Crawlora terms

More GDELT endpoint docs GDELT News Monitoring API Crawlora API pricing Try GDELT Timeline API in Playground 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
Platform: GDELT
Response schema: #/definitions/gdelt.timelineResponseDoc

Overview

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

Request parameters

Request parameters are generated from the active endpoint catalog. Required values must be sent before Crawlora can call the upstream public web data source.

Parameter	Type	Required	Description
query	string	Yes	GDELT query string. Same syntax as gdelt-search's query.
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.
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE.
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to	string	No	End of an absolute time window. Same formats as from.
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=coffee&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Authentication

Send your scraping API key in the x-api-key header. Use the console API Keys page to rotate or select the active key.

Billing

Endpoint usage is metered in credits. The plan prices, included credits, limits, and overage rates below match the active backend billing configuration.

Credit cost: 0 credits/request
Charged response: Successful 2xx responses

Plan	Price	Included credits	Daily cap	Rate limit	Overage
Free	$0/mo	2,000	500 daily credits	5/min	No overage
Starter	$9/mo	20,000	5,000 daily credits	15/min	$0.75/1,000 overage credits when enabled
Growth	$29/mo	100,000	25,000 daily credits	45/min	$0.45/1,000 overage credits when enabled
Pro	$79/mo	400,000	No daily cap	120/min	$0.30/1,000 overage credits
Business	$199/mo	1,200,000	No daily cap	300/min	$0.20/1,000 overage credits
Enterprise	$499/mo	5,000,000	No daily cap	1,000/min	$0.12/1,000 overage credits

Infrastructure behavior

This endpoint is executed through Crawlora's managed scraping infrastructure.

Proxy strategy: managed automatically where needed
Browser rendering: enabled for supported targets that require rendered HTML or JavaScript execution
Browser cluster: supported dynamic workloads can be routed through distributed browser instances
Retry behavior: automatic retry/fallback may be used depending on endpoint type
Challenge handling: challenged pages or unusable upstream HTML are detected and surfaced clearly when they cannot be used
Billing: credits are charged only for successful 2xx responses
Observability: responses include request context where available

Response behavior

Catalog quality warnings

missing example for required query param: query

Error behavior

Crawlora does not silently return bad data when the upstream page cannot be used.

Status	Common failure case
400	Invalid input or missing required parameter
429	Plan or endpoint rate limit exceeded
500	Internal execution error
502	Upstream platform failed, returned unusable HTML, or served a challenge page that could not be resolved

When possible, Crawlora returns structured error context so your integration can retry, back off, or inspect the request.

Failure responses

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

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

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=coffee&metric=volume&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Responsible public web data workflows

Read Crawlora terms

Open in Playground Back to group

GDELT Timeline API

Endpoint facts

Overview

Request parameters

cURL example

Authentication

Billing

Infrastructure behavior

Response behavior

Catalog quality warnings

Error behavior

Failure responses

Example JSON response

Code examples

Responsible public web data workflows

Related

GDELT Timeline API

Endpoint facts

Overview

Request parameters

cURL example

Authentication

Billing

Infrastructure behavior

Response behavior

Catalog quality warnings

Error behavior

Failure responses

Example JSON response

Code examples

Responsible public web data workflows

Related