Search Events
Discrete events we code in-house from news coverage into a CAMEO+ / ACLED-aligned taxonomy. Each carries: the ACTORS on both sides (actors, with their countries and roles), geography down to admin-1 with a stated precision, the linked story and its source articles, a written rationale, and a set of METRICS — significance (the default sort, and the only one meant to compare events across domains), plus magnitude, systemic_importance, propagation_potential and market_sensitivity, each filterable with <metric>_min / <metric>_max. Goldstein and quad class are published where the taxonomy defines them. Metric values also carry metrics.metric_inputs: the sub-factor scores the coder read off the article, each with the reason it gave — so a score can be audited rather than trusted. Definitions: https://docs.gdeltcloud.com/reference/metrics
Parameters this endpoint deliberately rejects (12)
Parameters this endpoint deliberately rejects (12)
These return a 400 with a reason rather than being silently ignored — a filter that looks accepted and does nothing produces a confident, wrong answer.
fatalities_min→ 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint, and were silently ignored before this rejection existed — a 200 of unfiltered rows under a lethality filter.fatalitiesis also a CONFLICT-family observable (the CAMEO+ family has no such field and serves null), so a range filter would quietly exclude 92.5% of events on top of that. Gate withhas_fatalities=true, then threshold thefatalitiesfield returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows,/api/v2/events/summaryreturnsfatalitiesandfatality_event_countper bucket. Use instead:has_fatalities=true,fatalities (response field — threshold client-side),/api/v2/events/summary?group_by=country.fatalities_max→ 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint, and were silently ignored before this rejection existed — a 200 of unfiltered rows under a lethality filter.fatalitiesis also a CONFLICT-family observable (the CAMEO+ family has no such field and serves null), so a range filter would quietly exclude 92.5% of events on top of that. Gate withhas_fatalities=true, then threshold thefatalitiesfield returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows,/api/v2/events/summaryreturnsfatalitiesandfatality_event_countper bucket. Use instead:has_fatalities=true,fatalities (response field — threshold client-side),/api/v2/events/summary?group_by=country.min_fatalities→ 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint, and were silently ignored before this rejection existed — a 200 of unfiltered rows under a lethality filter.fatalitiesis also a CONFLICT-family observable (the CAMEO+ family has no such field and serves null), so a range filter would quietly exclude 92.5% of events on top of that. Gate withhas_fatalities=true, then threshold thefatalitiesfield returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows,/api/v2/events/summaryreturnsfatalitiesandfatality_event_countper bucket. Use instead:has_fatalities=true,fatalities (response field — threshold client-side),/api/v2/events/summary?group_by=country.max_fatalities→ 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint, and were silently ignored before this rejection existed — a 200 of unfiltered rows under a lethality filter.fatalitiesis also a CONFLICT-family observable (the CAMEO+ family has no such field and serves null), so a range filter would quietly exclude 92.5% of events on top of that. Gate withhas_fatalities=true, then threshold thefatalitiesfield returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows,/api/v2/events/summaryreturnsfatalitiesandfatality_event_countper bucket. Use instead:has_fatalities=true,fatalities (response field — threshold client-side),/api/v2/events/summary?group_by=country.fatalities→ 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint, and were silently ignored before this rejection existed — a 200 of unfiltered rows under a lethality filter.fatalitiesis also a CONFLICT-family observable (the CAMEO+ family has no such field and serves null), so a range filter would quietly exclude 92.5% of events on top of that. Gate withhas_fatalities=true, then threshold thefatalitiesfield returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows,/api/v2/events/summaryreturnsfatalitiesandfatality_event_countper bucket. Use instead:has_fatalities=true,fatalities (response field — threshold client-side),/api/v2/events/summary?group_by=country.geo_scope→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.scope→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.detail→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.event_readiness→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.cluster_certainty→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.quad_class→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.as_of→ 400 UNSUPPORTED_PARAM. Event metrics are computed live and are not vintaged, so as_of cannot return a reproducible point-in-time result here. Use observed_start / observed_end to bound by when an event was coded, or the Atlas (/api/v2/intelligence/) and macro (/api/v2/macro/) endpoints for true point-in-time reads. Use instead:observed_start,observed_end,/api/v2/intelligence/gpr?as_of=,/api/v2/macro/*?as_of=.
Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. Also accepts: start_date. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Inclusive end of the window (YYYY-MM-DD). Also accepts: end_date. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Rolling window ending today, in days (max 30). window=7d and days=7 are equivalent. Also accepts: window. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Single-day anchor — equivalent to date_start = date_end = this value. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. Also accepts: observedStart. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Upper bound on the coded-at window. Also accepts: observedEnd. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Rows per page. Default 25, max 100. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
1 <= x <= 100Opaque pagination cursor taken from the previous response's pagination.next_cursor. Also accepts: offset. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
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: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/enums#country
One ACLED-style region. Expanded to its member countries. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Full value list: https://docs.gdeltcloud.com/reference/enums#region
Africa, Asia, Middle East, Northern Africa, Western Africa, Eastern Africa, Middle Africa, Southern Africa, Europe, Eastern Europe, South Asia, Southeast Asia, East Asia, Central Asia, North America, Central America, Caribbean, South America, Oceania One continent. Expanded to its member countries. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Full value list: https://docs.gdeltcloud.com/reference/enums#continent
Africa, Asia, Europe, North America, South America, Oceania Which definition of "in this country" the country / region / continent filters use. Defaults to the wider one, which is why omitting it changes nothing. Applies to region and continent too, since both expand into the same country set. Full value list: https://docs.gdeltcloud.com/reference/enums#country_match
location_or_actor_origin, location Sub-national admin1. Discover valid values with GET /api/v2/geo/admin1?country=. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/enums#admin1
Bounding box lat_min,lon_min,lat_max,lon_max. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Point proximity lat,lon, combined with radius_km. Applied as the enclosing bounding box, not a true distance filter — results are a deliberate superset. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Point proximity component (lat), an alternative spelling of near. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Point proximity component (lon), an alternative spelling of near. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Point proximity component (lng), an alternative spelling of near. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Radius in km for point proximity. Default 100, capped 2000. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Origin country of the ACTING side. Combine with target_actor_country to express a direction — source_actor_country=CHN&target_actor_country=USA,GBR is "China acting on those countries", which country= cannot say. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike country, region and continent do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. Matched case-insensitively. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Full value list: https://docs.gdeltcloud.com/reference/enums#country
Origin country of the RECEIVING side — the actor the action was directed at. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike country, region and continent do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. Matched case-insensitively. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Full value list: https://docs.gdeltcloud.com/reference/enums#country
Origin country of EITHER side, without regard to direction. This is the actor-origin half of what country= matches, on its own — use it to exclude events that merely happened in a country without any actor from it. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike country, region and continent do not expand onto the actor side. Matched case-insensitively. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Full value list: https://docs.gdeltcloud.com/reference/enums#country
Restrict to one entity's resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Also accepts: entity_id, entities. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle
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. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. 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. 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: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/taxonomy-complete
Deprecated. Prefer category, which implies the family. Deprecated since 2026-05; use category. Full value list: https://docs.gdeltcloud.com/reference/enums#event_family
conflict, cameoplus Deprecated CAMEO+ domain filter. Prefer category. Deprecated since 2026-05; use category. Full value list: https://docs.gdeltcloud.com/reference/enums#cameoplus_domain
POLITICAL, CRIME, ECONOMIC, CORPORATE, TECHNOLOGY, INFRASTRUCTURE, ENVIRONMENT, HEALTH, DEMOGRAPHIC, INFORMATION Significance lower bound (0–1). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#significance
0 <= x <= 1Significance upper bound (0–1). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#significance
0 <= x <= 1Confidence lower bound (0–1). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#confidence
0 <= x <= 1Confidence upper bound (0–1). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#confidence
0 <= x <= 1Goldstein scale lower bound (-10–10). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#goldstein_scale
-10 <= x <= 10Goldstein scale upper bound (-10–10). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#goldstein_scale
-10 <= x <= 10Magnitude lower bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/magnitude
0 <= x <= 10Magnitude upper bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/magnitude
0 <= x <= 10Systemic importance lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/systemic-importance
0 <= x <= 1Systemic importance upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/systemic-importance
0 <= x <= 1Propagation potential lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/propagation-potential
0 <= x <= 1Propagation potential upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/propagation-potential
0 <= x <= 1Market sensitivity lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/market-sensitivity
0 <= x <= 1Market sensitivity upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics/market-sensitivity
0 <= x <= 1Geo precision lower bound (1–3). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#geo_precision
1 <= x <= 3Geo precision upper bound (1–3). Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/metrics#geo_precision
1 <= x <= 3Semantic search — the string is embedded and ranked by cosine similarity, so results are conceptual neighbours rather than substring matches. There is no boolean parser: a query shaped a OR b is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE. Aliases q, query, keyword. Also accepts: q, query, keyword, name. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Ranking. A bare search with no explicit sort ranks by relevance instead. Full value list: https://docs.gdeltcloud.com/reference/enums#sort
significance, recent Restrict to events by whether they were checked for duplication. Comma-separated. Adjudication is deliberately partial, so llm,self is how you get the subset where incident.uid is a trustworthy grouping key; omitting the filter returns everything, most of which is unadjudicated. Also accepts: incident_resolutions. Full value list: https://docs.gdeltcloud.com/reference/enums#incident_resolution
unadjudicated, self, llm Add pagination.estimated_total — how many events match the filters, ignoring the page. Off by default because it costs a second scan of the same window. Counted from the SAME filters and the same row source as the page, so it always describes the result set you are walking. It is null (not a number) on a search= request: semantic retrieval is bounded by a candidate cap, so any total there would describe the candidate pool rather than the matching events. Without it, pagination.next_cursor still tells you whether more rows exist — non-null means yes, null means the walk is finished. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Restrict to events with a non-zero fatality count. CONFLICT FAMILY ONLY. fatalities is an ACLED-family observable; the CAMEO+ family has no fatality field, so its events carry fatalities: null (never a fabricated 0) and can never satisfy true. Over 2026-08-06..13 that was 92.5% of all events, including every ENVIRONMENT, INFRASTRUCTURE and HEALTH event — so a disaster or industrial death toll is NOT in this filter, and the total it sums is the armed-conflict toll, not a global one. false is not the complement: it returns both a conflict event coded with a real 0 and every event that has no fatality observable at all, so it means "not known to be lethal", never "known to be non-lethal". For a lethality screen across all families use significance_min (cross-domain by construction) or goldstein_scale_max — Goldstein is signed, so an upper bound like goldstein_scale_max=-5 selects the strongly conflictual end — and read fatalities off the card to tell a measured 0 from an absent observable. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Restrict to events coded as targeting civilians. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.
Source-language filter (ISO 639-1/2) on the linked Story's coverage. Also accepts: language. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language
Attach story images to each card. Off by default — images cost an extra lookup, so pass true to opt in. Also accepts: include_entity_images. Note: this parameter is documented and accepted, but validated by the service rather than the shared contract layer, so an invalid value may return an empty result rather than a 400.