Summarize Events

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

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, 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.

The dimension to aggregate over. Every dimension reconciles to the same total. Full value list: https://docs.gdeltcloud.com/reference/enums#event_group_by

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

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

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.

Distance in kilometres from the selected point for geographic proximity matching. 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

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. 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

Significance upper bound. 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

Explicit lexical required with search. Full value list: https://docs.gdeltcloud.com/reference/enums#reporting_summary_search_mode

Case-insensitive literal phrase in Event title/summary or Story title. Also accepts: q.

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: 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

Inclusive UTC date or instant: Event coded_at or Story updated_at. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Exclusive UTC date or instant: Event coded_at or Story updated_at. 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. 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

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

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

Typed selected root for a shared connected scope: entity or facility. Requires target_ids. Full value list: https://docs.gdeltcloud.com/reference/enums#target_type

Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. Requires target_type. Cannot be combined with entity. Use either the legacy entity filter or a typed target scope.

direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities. Requires target_type and target_ids. Full value list: https://docs.gdeltcloud.com/reference/enums#related_scope

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. 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

Confidence upper bound. 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

Goldstein scale lower bound. 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

Goldstein scale upper bound. 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

Magnitude lower bound. 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

Magnitude upper bound. 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

Systemic importance lower bound. 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

Systemic importance upper bound. 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

Propagation potential lower bound. 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

Propagation potential upper bound. 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

Market sensitivity lower bound. 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

Market sensitivity upper bound. 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

Geo precision lower bound. 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

Geo precision upper bound. 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