Summarize Events
Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Aggregate counts and metric statistics over the same Events /api/v2/events returns, grouped by date, country, region, continent, category or subcategory. Accepts every filter the list accepts, so a summary and a list of the same window are directly reconcilable. Metric averages are means over the rows where that metric is present, not over event_count — family-scoped metrics are genuinely absent on the other family.
Parameters this endpoint deliberately rejects (13)
Parameters this endpoint deliberately rejects (13)
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.
search→ 400 UNSUPPORTED_FILTER. search is only supported on list/search endpoints. Use /api/v2/events for semantic Event retrieval, then summarize with structured filters. Use instead:/api/v2/events.sort→ 400 UNSUPPORTED_PARAM. sort orders or pages ROWS, and a summary returns buckets. Uselimitto bound the number of buckets, or /api/v2/events to walk the underlying rows. Use instead:/api/v2/events,limit.cursor→ 400 UNSUPPORTED_PARAM. cursor orders or pages ROWS, and a summary returns buckets. Uselimitto bound the number of buckets, or /api/v2/events to walk the underlying rows. Use instead:/api/v2/events,limit.offset→ 400 UNSUPPORTED_PARAM. offset orders or pages ROWS, and a summary returns buckets. Uselimitto bound the number of buckets, or /api/v2/events to walk the underlying rows. Use instead:/api/v2/events,limit.include_images→ 400 UNSUPPORTED_PARAM. include_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/events for rows with images. Use instead:/api/v2/events.include_entity_images→ 400 UNSUPPORTED_PARAM. include_entity_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/events for rows with images. Use instead:/api/v2/events.geo_scope,scope,detail,event_readiness,cluster_certainty,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
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. For when we RECORDED it, use observed_start. 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). For when we RECORDED it, use observed_end. 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, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. 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.
Maximum number of BUCKETS returned (not rows). Default 50, max 500. There is no cursor on this endpoint, so a result at the limit may be truncated — widen the limit or narrow the 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.
1 <= x <= 500The dimension to aggregate over. Every dimension reconciles to the same total. Full value list: https://docs.gdeltcloud.com/reference/enums#event_group_by
date, country, region, continent, category, subcategory, source_actor_country, target_actor_country 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
One ACLED-style region. Expanded to its member countries. 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
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: 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 State or province (admin1), not a city. Discover valid values with GET /api/v2/geo/admin1?country=. 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#admin1
Point proximity lat,lon, combined with radius_km. The box is used for index pruning and rows are refined by true great-circle distance. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Radius in km for point proximity. Default 100, capped 2000. 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 an 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. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Also accepts: entity_id, 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
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
Significance lower bound (0–1). 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/metrics#significance
0 <= x <= 1Significance upper bound (0–1). 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/metrics#significance
0 <= x <= 1Restrict 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: 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 events coded as targeting civilians. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Coverage-language filter (ISO 639-1/2) on the underlying articles. 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. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language
OBSERVED TIME — inclusive start of the window by when GDELT Cloud RECORDED it, rather than when it happened: coding time on Events, cluster-update time on Stories. The supported point-in-time lever on this endpoint. For when it happened, use date_start. Accepts a calendar date (2026-08-01, read as that day at 00:00:00Z) OR a full instant (2026-08-01T04:04:30Z) — an instant is how you express a sub-day window, which date_start cannot. 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 TIME — exclusive upper bound on the recorded-at window (coding time on Events, cluster-update time on Stories). To include everything recorded through 2026-08-04, send 2026-08-05. Accepts a calendar date or a full instant (2026-08-05T04:04:30Z); the interval is half-open, so equal endpoints select no instant and are refused. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
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. 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 Bounding box lat_min,lon_min,lat_max,lon_max. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
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: 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#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: 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#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: 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#country
Coverage matching: Stories mentioning or linking the entity and the Events those Stories carry. The default and only supported policy; it does not establish actor participation or material involvement. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_match
coverage Which canonical ids the handle stands for. expand (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as applied_filters.entity_ids_expanded. exact restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_family
expand, exact Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (Q…) or the p_… id /api/v2/offices serves. Resolves to every holder whose published term overlaps the window (or office_as_of, when sent), then scopes exactly as entity=<those holders> would — a row is returned if ANY holder matches, and it is UNIONED with entity= when both are sent. A name is refused with 400; resolve it with GET /api/v2/offices?q= first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so applied_filters.office_holders discloses how many of the roster are bridged_to_news versus unbridged — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office's real coverage rather than a measurement of it. Each matched row carries entity_link.via: "office" with entity_link.entity naming the HOLDER (a spine id), not the office. Full value list: https://docs.gdeltcloud.com/reference/enums#office_id
VALID TIME for office= — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher's start/end clock, not what we knew then: it is NOT the knowledge-time as_of and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in applied_filters.office_holders.undated_excluded), never fabricated. Ignored without office.
Confidence lower bound (0–1). 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/metrics#confidence
0 <= x <= 1Confidence upper bound (0–1). 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/metrics#confidence
0 <= x <= 1Goldstein scale lower bound (-10–10). 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/metrics#goldstein_scale
-10 <= x <= 10Goldstein scale upper bound (-10–10). 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/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: 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/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: 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/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: 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/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: 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/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: 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/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: 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/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: 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/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: 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/metrics/market-sensitivity
0 <= x <= 1Geo precision lower bound (1–3). 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/metrics#geo_precision
1 <= x <= 3Geo precision upper bound (1–3). 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/metrics#geo_precision
1 <= x <= 3