Search Stories

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

Rows per page. Default 25, max 100. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Opaque pagination cursor taken from the previous response's pagination.next_cursor. Also accepts: offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

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

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

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

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

Search interpretation. semantic (default) retrieves a bounded conceptual relevance pool. lexical filters the complete serving set for a case-insensitive literal phrase in Events title/summary or Stories title before pagination; no stemming or boolean parsing. Lexical mode requires a supported serving snapshot and never falls back to the warehouse. Full value list: https://docs.gdeltcloud.com/reference/enums#reporting_search_mode

Search text. With search_mode=lexical this is a literal phrase in served Events title/summary or Stories title. By default 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. Also accepts: q. 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 that have (or have not) linked 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.

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 whose linked Events target 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.

Minimum article count. 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 article count. 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). 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

Attach article images to each card. Off by default. When enabled, entity thumbnails are also included unless include_entity_images=false. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Include entity thumbnails when include_images=true. Defaults to true, but has no effect while include_images is false or omitted. Pass false to skip the additional Wikipedia lookups while retaining article images. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Ranking. Full value list: https://docs.gdeltcloud.com/reference/enums#sort

Attach related Stories (schema 130). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Inclusive start of journal availability time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing their original reporting dates. Cannot combine with reporting-date filters. Event and Story lists return only identities first published in this interval. Baseline identities, updates, removals, and returning identities are excluded. Use /api/v2/activity for changes. 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 end of journal availability time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing their original reporting dates. Cannot combine with reporting-date filters. Event and Story lists return only identities first published in this interval. Baseline identities, updates, removals, and returning identities are excluded. Use /api/v2/activity for changes. 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 — 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

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

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

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.