Skip to main content
GET
Search list entries

Authorizations

​
Authorization
string
header
required

GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....

Query Parameters

​
list
enum<string>

The list to search, by source_key. source is an alias. Case-insensitive. The accepted set grows as sources are ingested: the values published here are the snapshot at build time, and /api/v2/lists (rows with ingested: true) is the live list. Also accepts: source. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#list_source_key

Available options:
csl_ofac_sdn,
csl_ofac_ssi,
csl_ofac_cmic,
csl_ofac_nsmbs,
csl_ofac_capta,
csl_bis_entity,
csl_bis_meu,
csl_bis_uvl,
csl_bis_dpl,
csl_state_debarred,
csl_state_isn,
dod_1260h,
un_consolidated,
uk_uksl
​
q
string

Case-insensitive substring over the entry name, its normalized form and every alias. search is an alias. Also accepts: search. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
country
string

Country of the entry — a name, ISO-2 or ISO-3. country_iso3 is an alias. Matched on the structured field OR the trailing ISO-2 token of an address, see coverage_warning. Also accepts: country_iso3. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
region
enum<string>

Region expanded to its countries (Eastern Europe). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Available options:
Middle East,
Northern Africa,
Western Africa,
Eastern Africa,
Middle Africa,
Southern Africa,
Eastern Europe,
South Asia,
Southeast Asia,
East Asia,
Central Asia,
Northern America,
Central America,
Caribbean
​
continent
enum<string>

Continent expanded to its countries (Asia). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Available options:
Africa,
Asia,
Europe,
North America,
South America,
Oceania
​
program
string

Sanctions programme code, matched case-insensitively (UKRAINE-EO13662). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
entity
string

Only entries resolved to this entity — an e_ spine id or a wiki: news id, collapsed through the arbiter. entity_id is an alias. An id the registry has never heard of answers 400 UNRESOLVED_ENTITY_ID rather than an empty list. Also accepts: entity_id. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
active_on
string<date>

Point-in-time: entries on the list on this date, by our observation history. A date outside coverage_window answers screen_status: inconclusive with the window, never an empty list. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
added_since
string<date>

Only entries first observed on or after this date. Ignored when active_on or removed_since is set. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
removed_since
string<date>

Only entries that LEFT a list on or after this date (active: false). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
sort
enum<string>
default:name

name (A–Z) or recent (latest observation first). Full value list: https://docs.gdeltcloud.com/reference/enums#list_entries_sort

Available options:
name,
recent
​
limit
integer
default:25

Maximum entries returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor from pagination.next_cursor. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

​
offset
integer

Legacy numeric offset; cursor is preferred. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Required range: x >= 0

Response

Search list entries.

​
success
boolean
required
​
data
object[]
required
​
pagination
object
required
​
sort
string | null
required
​
applied_filters
any
required
​
screen_status
enum<string>
Available options:
inconclusive
​
inconclusive_reason
enum<string>
Available options:
active_on_precedes_coverage,
active_on_follows_coverage
​
coverage_window
object
​
coverage_warning
string

Present when a country/region/continent filter could only be honoured best-effort. Treat a miss as "no match on file", NOT "not sanctioned".

​
note
string