Summarize Stories
Continuous stories coverage begins 2026-03-08. 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 statistics over the same Stories /api/v2/stories returns, grouped by date, country, region, continent, category or subcategory. Event-scoped filters are applied inside the linked-event rollup, so a story’s counts reflect the events that matched your filters rather than its total. With group_by=country, country_attribution=all counts each distinct Story under every country matching the ordinary Stories country filter. Country buckets may overlap; use group_by=date for distinct global totals.
Parameters this endpoint deliberately rejects (14)
Parameters this endpoint deliberately rejects (14)
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.
event_family→ 400 UNSUPPORTED_PARAM. event_family is not supported on the Stories summary — a Story is not scoped to one event family. Filter the linked events with event_category, or use /api/v2/events/summary. Use instead:event_category,/api/v2/events/summary.search→ 400 UNSUPPORTED_FILTER. search is only supported on list/search endpoints. Use /api/v2/stories for semantic Story retrieval, then summarize with structured filters. Use instead:/api/v2/stories.sort→ 400 UNSUPPORTED_PARAM. sort orders or pages ROWS, and a summary returns buckets. Uselimitto bound the number of buckets, or /api/v2/stories to walk the underlying rows. Use instead:/api/v2/stories,limit.cursor→ 400 UNSUPPORTED_PARAM. cursor orders or pages ROWS, and a summary returns buckets. Uselimitto bound the number of buckets, or /api/v2/stories to walk the underlying rows. Use instead:/api/v2/stories,limit.offset→ 400 UNSUPPORTED_PARAM. offset orders or pages ROWS, and a summary returns buckets. Uselimitto bound the number of buckets, or /api/v2/stories to walk the underlying rows. Use instead:/api/v2/stories,limit.include_images→ 400 UNSUPPORTED_PARAM. include_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/stories for rows with images. Use instead:/api/v2/stories.include_entity_images→ 400 UNSUPPORTED_PARAM. include_entity_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/stories for rows with images. Use instead:/api/v2/stories.geo_scope,scope,detail,event_readiness,cluster_certainty,total_events→ 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/total_events selectors.as_of→ 400 UNSUPPORTED_PARAM. Stories retain their current settled representation, not every historical version. as_of therefore cannot reconstruct Story counts or attributes as they were known on that date. Use observed_start / observed_end to bound when Stories entered the product, or a genuinely vintaged endpoint for reproducible values. Use instead:observed_start,observed_end,/api/v2/intelligence/gpr?as_of=,/api/v2/macro/observations?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. Country buckets overlap when country_attribution=all; use group_by=date for distinct totals. Full value list: https://docs.gdeltcloud.com/reference/enums#story_group_by
date, country, region, continent, category, subcategory For group_by=country: primary preserves one primary country per Story; all counts each Story under every authoritative country attribution or linked Event location/actor origin, using the same country_match and other filters as the Stories list. Explicit geographic filters also restrict the emitted country buckets. Buckets overlap and must not be summed as a global total. Other groupings ignore this option. Full value list: https://docs.gdeltcloud.com/reference/enums#story_country_attribution
primary, all 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. A Story also matches on its OWN attributed country, so Stories with no coded Event are reachable — over 2026-08-14..16 that took the reachable set from 5,386 to 24,207 of 25,463 Stories. Combining country with an Event-scoped filter (event_category, subcategory, admin1, bbox, domain, civilian_targeting) keeps the Event-only definition, because those ask about the Story's Events. Attribution begins 2026-07; earlier windows are Event-derived only. 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
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. On Stories this filters the LINKED EVENTS. Passing a Story cluster label here (for example cameoplus_political) is a legacy alias for story_category and is applied as one — a materially different filter, so prefer story_category for a Story label and keep category for linked-event taxonomy. applied_filters reports which one received it. 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
Story-level topic, comma-separated for OR. Distinct from the EVENT taxonomy that category filters. Full value list: https://docs.gdeltcloud.com/reference/enums#story_category
conflict_security, cameoplus_political, cameoplus_crime, cameoplus_economic, cameoplus_corporate, cameoplus_technology, cameoplus_infrastructure, cameoplus_environment, cameoplus_health, cameoplus_demographic, cameoplus_information, CONFLICT, CORPORATE, CRIME, DEMOGRAPHIC, ECONOMIC, ENVIRONMENT, HEALTH, INFORMATION, INFRASTRUCTURE, POLITICAL, TECHNOLOGY Restrict to Stories with at least one linked Event. 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 Stories whose linked events carry fatalities. 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". Stories publish no metric filters, so for a cross-family severity screen query /api/v2/events — which does — and follow story_refs back. Read fatalities off each linked event 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 Stories with civilian-targeting 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.
Lower bound on the number of source articles behind a Story. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
x >= 1Upper bound on the number of source articles behind a Story. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
x >= 1Coverage-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.
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.