Skip to main content
GET
cURL

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
search
string

Entity name or phrase to search for. Aliases q, query, keyword, and name are accepted (first non-empty wins); for high-recall cross-source discovery see GET /api/v2/search. Resolved filters are echoed in the response applied_filters block, with unrecognized params under applied_filters.ignored.

​
type
enum<string>

Optional entity type filter. place covers geographies (countries, cities, regions), typed from Wikidata P31 — before 2026-07-30 these were mis-filed under organization and person, so type=organization returned countries. Roles and offices are deliberately none of these three and are excluded rather than mislabelled.

Available options:
person,
organization,
place
​
date_start
string<date>

Inclusive start date in YYYY-MM-DD, matched against the event or story date. Alias start_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.

Example:

"2026-04-11"

​
date_end
string<date>

Inclusive end date in YYYY-MM-DD, matched against the event or story date. Alias end_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.

Example:

"2026-04-17"

​
event_family
enum<string>

Deprecated legacy filter. Prefer category, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility.

Available options:
conflict,
cameoplus
​
category
string

Stable linked Event product category. Use a Conflict event type such as Battles, Protests, or Explosions/Remote violence, or one CAMEO+ domain such as POLITICAL, INFRASTRUCTURE, or CRIME; values may be single or comma-separated. On Story endpoints this filters linked Event evidence. Use story_category only for legacy Story-cluster categories such as conflict_security. Full list: Taxonomy & Codes.

Example:

"Battles"

​
subcategory
string

More specific linked Event subtype, CAMEO+ event description, or CAMEO+ code. Requires parent category and must belong to at least one selected category. For Conflict categories, use sub-event types such as Armed clash, Peaceful protest, or Air/drone strike. Validation errors include accepted_values, nearest_values when practical, and a corrected example. Full list: Taxonomy & Codes.

Example:

"Armed clash"

​
domain
enum<string>

Deprecated legacy CAMEO+ domain enum. Prefer category/categories for new integrations; retained for backwards compatibility. Full list: Taxonomy & Codes.

Available options:
POLITICAL,
ECONOMIC,
CORPORATE,
TECHNOLOGY,
INFRASTRUCTURE,
HEALTH,
DEMOGRAPHIC,
INFORMATION,
ENVIRONMENT,
CRIME
​
has_fatalities
boolean

Set true for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.

Example:

true

​
civilian_targeting
boolean

Filter Conflict-linked evidence by ACLED civilian_targeting. true keeps records where civilians are the primary target; false excludes those records.

​
sort
enum<string>
default:significance

significance is the default analyst ranking. Use recent when freshness matters more than importance.

Available options:
significance,
recent
Example:

"significance"

​
limit
integer
default:25

Number of records to return.

Required range: 1 <= x <= 100
Example:

25

​
cursor
string

Pagination cursor from pagination.next_cursor.

Response

200 - application/json

Entity cards

​
success
enum<boolean>
Available options:
true
​
pagination
object
​
data
object[]