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.

Only Situations containing this currently served 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.

Only Situations containing a served Story linked to this coded 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 — a case-insensitive match requiring EVERY whitespace-separated term to appear somewhere in it, so nepal flood matches "Flash floods hit northern Nepal-Tibet border". What it CANNOT do, because there is nothing behind it to do it with: it does not read the member Stories, their article text or their entities; it is not semantic, so a synonym finds nothing; and title is the PEAK member's headline, re-stamped every time the Situation is recomputed — a term that matched yesterday can stop matching tomorrow without the occurrence changing. 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 (default) uses latest reporting date, then first-observed membership time; created orders by immutable creation time, newest first; 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

Situations per page. Default 25, max 200. 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.

Situations to skip. This endpoint pages by offset and has no cursor — every sort is a total order (ties break on situation_uid), so an offset walk cannot repeat or skip a row.

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