Docs menu

GDELT API endpoint

GDELT Context Search API

Searches the last 72 hours of GDELT-monitored news for sentences where every term of the required `query` appears together. Returns up to `maxrecords` rows (default 75, max 200), each with the matching sentence, its surrounding context, title, URL, domain, language and an `is_quote` flag. Filter with `domain`, `language`, `is_quote`, `timespan` or `from` and `to`, and order with `sort`.

GETapiKey0 credits/requestGDELTgdelt.contextResponseDoc/gdelt/context

Endpoint facts

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

GDELT News Monitoring API Try GDELT Context Search API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. All terms must co-occur in the same sentence (unlike gdelt-search). Supports quoted phrases, boolean OR ((a OR b)), and domain:example.com.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
language (optional) — source-language filter (GDELT's searchlang parameter, a top-level parameter for this endpoint, not a query clause). Space-segmented languages only (excludes CJK and similar).
is_quote (optional, default false) — only return sentences GDELT identified as a quotation.
timespan (optional) — relative time window ending now, e.g. 30min, 6h, 3d. Cannot be combined with from/to. GDELT caps this endpoint's window at 72 hours (unlike gdelt-search's ~3 months) — requesting more is rejected before the request even reaches GDELT.
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.
sort (optional, default relevance) — result order. Allowed values: relevance, datedesc, dateasc. (No tonedesc/toneasc — not supported by this endpoint, unlike gdelt-search.)
maxrecords (optional, default 75) — rows to return. GDELT's own hard cap here is 200 (lower than gdelt-search's 250).

Notable response behavior:

sentence is the single matching sentence (GDELT returns at most one matching sentence per article); context is the surrounding paragraph.
count is the number of articles actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error).
source_url is the exact upstream GDELT Context API URL used for the call.
A GDELT-side rate limit, a timespan/date range GDELT itself rejects as out of its 72-hour window, or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data. An out-of-range timespan is instead rejected client-side as a 400 before ever reaching GDELT (see the timespan note above); an out-of-range from/to combination is not independently validated client-side and falls through to GDELT's own 503-classified rejection.

Sampled response

Request, 14 Oct 2026: GET /gdelt/context?query=climate+%28flood+OR+drought%29&timespan=24h
Items in articles: 74
Fields filled in every checked item: 8
Fields empty in some or all items: 1

Field	Filled in, of 74 checked	Values in the sample
url	74	pressdemocrat.com and 69 other hosts
title	74	“A historic El Niño is gathering strength. Heres how to prep…” and 30 other values
seen_at	74	2026-10-13
domain	74	“pressdemocrat.com” and 69 other values
language	74	ENGLISH in all 74
social_image_url	69	pressdemocrat.com and 28 other hosts
is_quote	74	true in 4 of 74
sentence	74	median 221 characters
context	74	median 455 characters

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. All terms must co-occur in the same sentence. Supports quoted phrases, (a OR b), domain:example.com.	climate change
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
language	string	No	Source-language filter (GDELT's searchlang parameter). Space-segmented languages only (excludes CJK and similar).	english
is_quote	boolean	No	Only return sentences GDELT identified as a quotation.
timespan	string	No	Relative time window ending now, e.g. 30min, 6h, 3d. Cannot be combined with from/to. GDELT caps this endpoint's window at 72 hours.	24h
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan; GDELT caps this endpoint's window at 72 hours.	2026-08-19
to	string	No	End of an absolute time window. Same formats as from.	2026-08-20
sort	string	No	Result order. Allowed values: relevance, datedesc, dateasc.
maxrecords	integer	No	Rows to return. GDELT's own hard cap is 200 for this endpoint (lower than gdelt-search's 250); there is no pagination cursor beyond it. Minimum: 1. Maximum: 200.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/context?query=climate+change&language=en&is_quote=true&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "climate change",
    "sort": "relevance",
    "maxrecords": 75,
    "count": 1,
    "source_url": "https://api.gdeltproject.org/api/v2/context/context?format=json&maxrecords=75&mode=artlist&query=climate+change&timespan=24h",
    "fetched_at": "2026-08-20T10:00:00Z",
    "articles": [
      {
        "url": "https://www.example.com/news/climate-report",
        "title": "Climate report warns of rising sea levels",
        "seen_at": "2026-08-19T23:00:00Z",
        "domain": "example.com",
        "language": "ENGLISH",
        "social_image_url": "https://www.example.com/images/social.jpg",
        "is_quote": false,
        "sentence": "Coastal cities face rising seas driven by accelerating climate change.",
        "context": "The report, released Tuesday, warns that coastal cities face rising seas driven by accelerating climate change. Officials called for immediate action."
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.contextResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.ContextResponse	No
data.articles	array	No
data.articles[].context	string	No	The report, released Tuesday, warns that coastal cities face rising seas driven by accelerating climate change. Officials called for immediate action.
data.articles[].domain	string	No	example.com
data.articles[].is_quote	boolean	No	false
data.articles[].language	string	No	ENGLISH
data.articles[].seen_at	string	No	2026-08-19T23:00:00Z
data.articles[].sentence	string	No	Coastal cities face rising seas driven by accelerating climate change.
data.articles[].social_image_url	string	No	https://www.example.com/images/social.jpg
data.articles[].title	string	No	Climate report warns of rising sea levels
data.articles[].url	string	No	https://www.example.com/news/climate-report
data.count	integer	No	8
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.maxrecords	integer	No	75
data.query	string	No	climate change
data.sort	string	No	relevance
data.source_url	string	No	https://api.gdeltproject.org/api/v2/context/context?format=json&maxrecords=75&mode=artlist&query=climate+change&timespan=24h
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/context?query=climate+change&language=en&is_quote=true&sort=relevance" \
  -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 Search API documentation GDELT Timeline 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 Context Search API

GETapiKey0 credits/requestGDELTgdelt.contextResponseDoc/gdelt/context

Endpoint facts

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

GDELT News Monitoring API Try GDELT Context Search API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. All terms must co-occur in the same sentence (unlike gdelt-search). Supports quoted phrases, boolean OR ((a OR b)), and domain:example.com.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
language (optional) — source-language filter (GDELT's searchlang parameter, a top-level parameter for this endpoint, not a query clause). Space-segmented languages only (excludes CJK and similar).
is_quote (optional, default false) — only return sentences GDELT identified as a quotation.
timespan (optional) — relative time window ending now, e.g. 30min, 6h, 3d. Cannot be combined with from/to. GDELT caps this endpoint's window at 72 hours (unlike gdelt-search's ~3 months) — requesting more is rejected before the request even reaches GDELT.
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.
sort (optional, default relevance) — result order. Allowed values: relevance, datedesc, dateasc. (No tonedesc/toneasc — not supported by this endpoint, unlike gdelt-search.)
maxrecords (optional, default 75) — rows to return. GDELT's own hard cap here is 200 (lower than gdelt-search's 250).

Notable response behavior:

sentence is the single matching sentence (GDELT returns at most one matching sentence per article); context is the surrounding paragraph.
count is the number of articles actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error).
source_url is the exact upstream GDELT Context API URL used for the call.
A GDELT-side rate limit, a timespan/date range GDELT itself rejects as out of its 72-hour window, or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data. An out-of-range timespan is instead rejected client-side as a 400 before ever reaching GDELT (see the timespan note above); an out-of-range from/to combination is not independently validated client-side and falls through to GDELT's own 503-classified rejection.

Sampled response

Request, 14 Oct 2026: GET /gdelt/context?query=climate+%28flood+OR+drought%29&timespan=24h
Items in articles: 74
Fields filled in every checked item: 8
Fields empty in some or all items: 1

Field	Filled in, of 74 checked	Values in the sample
url	74	pressdemocrat.com and 69 other hosts
title	74	“A historic El Niño is gathering strength. Heres how to prep…” and 30 other values
seen_at	74	2026-10-13
domain	74	“pressdemocrat.com” and 69 other values
language	74	ENGLISH in all 74
social_image_url	69	pressdemocrat.com and 28 other hosts
is_quote	74	true in 4 of 74
sentence	74	median 221 characters
context	74	median 455 characters

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. All terms must co-occur in the same sentence. Supports quoted phrases, (a OR b), domain:example.com.	climate change
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
language	string	No	Source-language filter (GDELT's searchlang parameter). Space-segmented languages only (excludes CJK and similar).	english
is_quote	boolean	No	Only return sentences GDELT identified as a quotation.
timespan	string	No	Relative time window ending now, e.g. 30min, 6h, 3d. Cannot be combined with from/to. GDELT caps this endpoint's window at 72 hours.	24h
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan; GDELT caps this endpoint's window at 72 hours.	2026-08-19
to	string	No	End of an absolute time window. Same formats as from.	2026-08-20
sort	string	No	Result order. Allowed values: relevance, datedesc, dateasc.
maxrecords	integer	No	Rows to return. GDELT's own hard cap is 200 for this endpoint (lower than gdelt-search's 250); there is no pagination cursor beyond it. Minimum: 1. Maximum: 200.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/context?query=climate+change&language=en&is_quote=true&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "climate change",
    "sort": "relevance",
    "maxrecords": 75,
    "count": 1,
    "source_url": "https://api.gdeltproject.org/api/v2/context/context?format=json&maxrecords=75&mode=artlist&query=climate+change&timespan=24h",
    "fetched_at": "2026-08-20T10:00:00Z",
    "articles": [
      {
        "url": "https://www.example.com/news/climate-report",
        "title": "Climate report warns of rising sea levels",
        "seen_at": "2026-08-19T23:00:00Z",
        "domain": "example.com",
        "language": "ENGLISH",
        "social_image_url": "https://www.example.com/images/social.jpg",
        "is_quote": false,
        "sentence": "Coastal cities face rising seas driven by accelerating climate change.",
        "context": "The report, released Tuesday, warns that coastal cities face rising seas driven by accelerating climate change. Officials called for immediate action."
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.contextResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.ContextResponse	No
data.articles	array	No
data.articles[].context	string	No	The report, released Tuesday, warns that coastal cities face rising seas driven by accelerating climate change. Officials called for immediate action.
data.articles[].domain	string	No	example.com
data.articles[].is_quote	boolean	No	false
data.articles[].language	string	No	ENGLISH
data.articles[].seen_at	string	No	2026-08-19T23:00:00Z
data.articles[].sentence	string	No	Coastal cities face rising seas driven by accelerating climate change.
data.articles[].social_image_url	string	No	https://www.example.com/images/social.jpg
data.articles[].title	string	No	Climate report warns of rising sea levels
data.articles[].url	string	No	https://www.example.com/news/climate-report
data.count	integer	No	8
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.maxrecords	integer	No	75
data.query	string	No	climate change
data.sort	string	No	relevance
data.source_url	string	No	https://api.gdeltproject.org/api/v2/context/context?format=json&maxrecords=75&mode=artlist&query=climate+change&timespan=24h
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/context?query=climate+change&language=en&is_quote=true&sort=relevance" \
  -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 Context Search API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

GDELT Context Search API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related