List Situations

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

Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Stored Situation UID from search_situations, or a member Story ID when supported by this operation; reuse the returned identifier. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Coded Event UID from search_events; selects Situations with member Stories linked to that 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.

Include country aggregates over every matching Situation, independently of page size. Requires a reporting window of at most 30 days.

Return Situations still running on or after this date (YYYY-MM-DD) — matched against span_end, so an occurrence that began earlier and is ongoing IS returned. Optional and independent of date_end. There is no maximum span: the Situations table is one row per adjudicated occurrence and is small by construction, so this is a filter on a stored column rather than a bound on how much is scanned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Return Situations that had already begun by this date (YYYY-MM-DD) — matched against span_start. Sent together with date_start the pair selects every occurrence whose span OVERLAPS the window; sent alone it leaves the other side open. An inverted pair is refused with INVALID_DATE_RANGE rather than answered empty. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Free text matched against the stored title OR the headline of any member Story reported inside the window (the last 30 days when no dates are sent) — a case-insensitive match requiring EVERY whitespace-separated term to appear in one of the two, so nepal flood matches "Flash floods hit northern Nepal-Tibet border" and AI slowdown finds a Situation titled "Trump says US will not slow AI race" through a member headline that says slowdown. The phrase also runs through the hybrid GET /api/v2/stories?search= in the same window, and a Situation holding one of the top-ranked Stories matches too, so AI pause can reach the same Situation through meaning; meta.search.semantic_story_candidates reports how many Story hits that arm contributed and meta.search.note says when it was unavailable. What it CANNOT do: read article text or entities directly; and title is the PEAK member's headline, re-stamped every time the Situation is recomputed. At most 8 terms; more is refused with INVALID_SEARCH rather than silently truncated. To search what a Situation is actually ABOUT, run GET /api/v2/stories?search= and take any returned Story id to /api/v2/situations/{story_id}. 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 member Stories across the whole current servable membership, not the selected reporting window. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds. This filter does not change creation, growth or direct UID lookup.

Minimum articles across the member Stories — the best single proxy for how big an occurrence got, and the default sort key. Compared against the stored article_count.

Minimum coded Events at canonical-incident grain across the whole current servable membership. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds, including reporting with no coded Events. Explicit zero is permitted.

Ranking. recent uses latest reporting date, then first-observed membership time; created orders by immutable creation time, newest first; updated orders by the latest serving-membership refresh; article_count, story_count and event_count are volume alternatives; span_days puts the longest-running occurrence first — the inclusive day count between span.start and span.end, with an unmeasured span last. Recent never uses refresh time or volume. Every order breaks ties on situation_uid, so paging with offset is stable. Full value list: https://docs.gdeltcloud.com/reference/enums#situation_sort

Number of Situations returned on this page. pagination.total is the true number matching your filters, counted separately from the page, so has_more is measured rather than inferred from a full page. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Number of records to skip before this page.

Any member-linked coded Event located in this ISO-3 country. Actor nationality is not used. Requires date_start and date_end, at most 30 inclusive days. Both country and category match the SAME 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. Full value list: https://docs.gdeltcloud.com/reference/enums#country