curl --request GET \
--url https://gdeltcloud.com/api/v2/entities \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/entities"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/entities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": [
{
"id": "https://en.wikipedia.org/wiki/United_Nations",
"url": "https://gdeltcloud.com/entities/e_united_nations",
"name": "United Nations",
"type": "organization",
"wikipedia_url": "https://en.wikipedia.org/wiki/United_Nations",
"story_refs": [],
"event_refs": []
}
],
"pagination": {
"limit": 25,
"cursor": null,
"next_cursor": "eyJvZmZzZXQiOjI1fQ=="
}
}Discover entities in reporting
Discover people, organizations and places appearing in reporting. For initial identity lookup, use /api/v2/search?q=…, select a candidate, then reuse its ID on the destination endpoint. This endpoint returns coverage metrics over the requested window. search= resolves a NAME across every entity universe we hold — news, the GDELT Cloud spine (SEC/EDGAR, GLEIF, GEM), sanctions lists, China-Abroad and Epoch — and each row reports the same entity_id join key as /api/v2/search (with legacy id retained), plus match_type / match_reason / match_score so the ranking can be audited rather than trusted. Metrics are the entity’s resolved-layer coverage IN THE WINDOW, so a searched company with a successful empty coverage read reports zeros. Failed count reads report null with coverage_status; quiet reference matches remain available through search. Without search, the news-activity directory excludes measured-zero coverage rows. For the cross-source candidate list with per-source availability, use /api/v2/search. Native non-Latin-script matching is not yet complete, so use a common Romanized or English spelling for Cyrillic, Chinese and other non-Latin names for now. Native-script search support is on the way.
Parameters this endpoint deliberately rejects (1)
Parameters this endpoint deliberately rejects (1)
These return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.
entity→ 400 UNSUPPORTED_FILTER. This endpoint LISTS entities; it does not scope to one.entity=means “restrict to this entity’s coverage” on /api/v2/events and /api/v2/stories, and it cannot mean that here. For the entities that appear alongside one entity useco_occurring_with=; for one entity’s own record useGET /api/v2/entities/{entity_id}; for its coverage use/api/v2/events?entity=or/api/v2/stories?entity=. The handle is the same in all four. Use instead:co_occurring_with=<handle>,GET /api/v2/entities/{entity_id},GET /api/v2/events?entity=<handle>,GET /api/v2/stories?entity=<handle>.
curl --request GET \
--url https://gdeltcloud.com/api/v2/entities \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/entities"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/entities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": [
{
"id": "https://en.wikipedia.org/wiki/United_Nations",
"url": "https://gdeltcloud.com/entities/e_united_nations",
"name": "United Nations",
"type": "organization",
"wikipedia_url": "https://en.wikipedia.org/wiki/United_Nations",
"story_refs": [],
"event_refs": []
}
],
"pagination": {
"limit": 25,
"cursor": null,
"next_cursor": "eyJvZmZzZXQiOjI1fQ=="
}
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
EVENT TIME — inclusive start of the window by when it HAPPENED (YYYY-MM-DD). Windows are capped at 30 inclusive days. Use consecutive date chunks; calendar months can exceed the cap. Follow the endpoint's pagination guidance within each chunk. Also accepts: start_date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). Also accepts: end_date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Calendar-date window ending today, in days (max 30). window=7d and days=7 are equivalent. When omitted, entity coverage uses the last 30 calendar days with an observed-time bound over the same span. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass days explicitly, or date_start/date_end, whenever the window matters. Also accepts: window. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Number of records to return on this page; use the returned continuation to request the next page. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
1 <= x <= 100Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. Also accepts: offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Return the entities that appear ALONGSIDE this one — the entities linked to the same Stories, over the same window, narrowed by every other filter on this endpoint. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the same arbiter as entity= on /api/v2/events and /api/v2/stories, so one handle means the same entity everywhere. The subject is never returned in its own results. Co-occurrence is measured over SHARED STORIES — appearing in the same coverage, which is not a claim that the two entities interacted. A handle that resolves to nothing returns an EMPTY list with a linkage reason in applied_filters, never the global top entities. 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#entity_handle
Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event's own location OR either actor's origin country by default, so a result can include events that happened elsewhere — set country_match to narrow it to location only. The definition in force is echoed as applied_filters.country_match. Also accepts: country_iso3. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#country
Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules. 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#region
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 expanded to its member ISO-3 countries; applied through the same country matching rules. 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#continent
Africa, Asia, Europe, North America, South America, Oceania Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with subcategory: an impossible pair returns 400, never an empty 200. Also accepts: categories. Matched case-insensitively. 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#event_category
Battles, Protests, Riots, Explosions/Remote violence, Violence against civilians, Strategic developments, POLITICAL, CRIME, ECONOMIC, CORPORATE, TECHNOLOGY, INFRASTRUCTURE, ENVIRONMENT, HEALTH, DEMOGRAPHIC, INFORMATION Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by category — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (Sexual violence is the measured example: its definition boundary sends nearly all such reporting to Attack). Before building a monitor on one code, measure it: GET /api/v2/events/summary?group_by=subcategory returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/taxonomy-complete
Restrict to one or more comma-separated entity types. entity_type is accepted as an alias because that is the id /meta/enums publishes for this vocabulary. Also accepts: entity_type. 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#entity_type
PERSON, ORGANIZATION, PLACE Entity NAME to resolve. Matched across every entity universe and ranked by match quality (exact name, exact alias, acronym, prefix, fuzzy) before coverage — see each row's match_type and match_reason. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names. Also accepts: q. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
ISO source-language filter. Restricts coverage metrics to articles in those languages. Also accepts: language. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Observed vocabulary, measured 2026-08-10 (77 distinct values). Values outside it are accepted, not rejected. Discover current values: GET /api/v2/stories?limit=1 (read coverage.languages). Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#coverage_language
Restrict to entities linked to fatal events. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Restrict to entities linked to events coded as civilian targeting. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
recent orders an unfiltered directory by latest Story reporting time (latest_observed_news_at), then Story and article volume within the same timestamp. Filtered/search requests retain candidate news-date precision (latest_observed_news_date) because those predicates are not all materialized on serving Stories. Registry or link-processing times never lead. With significance, search resolves by match quality first; resolved counts and latest_date do not reorder the fixed candidate page. 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#sort
significance, recent Attach Wikipedia thumbnail/avatar URLs where available. Off unless requested — the images cost an extra lookup. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Inclusive start of API publication time, as an ISO UTC timestamp. Includes late arrivals without changing when the event happened. Requires recorded_end. Cannot be combined with date_start, date_end or days. A recorded interval replaces the reporting window.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$Exclusive end of API publication time, as an ISO UTC timestamp. Includes late arrivals without changing when the event happened. Requires recorded_start. Cannot be combined with date_start, date_end or days. A recorded interval replaces the reporting window.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$Which definition of "in this country" the country / region / continent filters use. Applies to region and continent too, since both expand into the same country set. Note that group_by=country buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass country_match=location when you need the two to agree. Full value list: https://docs.gdeltcloud.com/reference/enums#country_match
location_or_actor_origin, location