GDELT Cloud Docs — Global Event Data API & MCP

The per-endpoint tables below cover the endpoints whose parameters are governed by the contract registry — the descriptors the server imports at request time, so a parameter listed there is one the server actually parses and a parameter absent from it is one that endpoint ignores. The remaining operations publish their parameters in the API reference; the identifier section below is derived from the whole published surface.

Shared parameters

76 parameter names appear on more than one endpoint. When bounds or defaults differ, use the per-endpoint tables below.

Parameter	Type	Constraints	On
`actor_country`	enum `country`	case-insensitive	2 endpoints
`admin1`	csv	—	4 endpoints
`article_count_max`	number	Varies by endpoint; see below	2 endpoints
`article_count_min`	number	Varies by endpoint; see below	2 endpoints
`as_of`	date	—	8 endpoints
`basis`	string	default `publication`	2 endpoints
`bbox`	bbox	—	5 endpoints
`category`	enum `event_category`	Varies by endpoint; see below	8 endpoints
`civilian_targeting`	boolean	—	5 endpoints
`confidence_max`	number	min 0, max 1	2 endpoints
`confidence_min`	number	min 0, max 1	2 endpoints
`continent`	enum `continent`	—	12 endpoints
`country`	enum `country`	Varies by endpoint; see below	16 endpoints
`country_match`	enum `country_match`	Varies by endpoint; see below	6 endpoints
`cursor`	string	—	14 endpoints
`date`	date	—	6 endpoints
`date_end`	date	—	18 endpoints
`date_start`	date	—	18 endpoints
`days`	duration	Varies by endpoint; see below	10 endpoints
`end_date`	date	—	2 endpoints
`entity`	string	—	9 endpoints
`entity_family`	enum `entity_family`	default `expand`	4 endpoints
`entity_match`	enum `entity_match`	default `coverage`	4 endpoints
`geo`	string	—	2 endpoints
`geo_precision_max`	number	min 1, max 3	2 endpoints
`geo_precision_min`	number	min 1, max 3	2 endpoints
`goldstein_scale_max`	number	min -10, max 10	2 endpoints
`goldstein_scale_min`	number	min -10, max 10	2 endpoints
`group_by`	enum `event_group_by`	Varies by endpoint; see below	3 endpoints
`has_events`	boolean	—	2 endpoints
`has_fatalities`	boolean	—	5 endpoints
`hour`	integer	min 0, max 23	3 endpoints
`include`	enum `facility_context_include`	—	2 endpoints
`include_entity_images`	boolean	default `true`	2 endpoints
`include_images`	boolean	Varies by endpoint; see below	5 endpoints
`languages`	csv	—	6 endpoints
`level`	enum `atlas_level`	Varies by endpoint; see below	2 endpoints
`limit`	limit	Varies by endpoint; see below	29 endpoints
`list`	enum `exposure_list`	Varies by endpoint; see below	3 endpoints
`magnitude_max`	number	min 0, max 10	2 endpoints
`magnitude_min`	number	min 0, max 10	2 endpoints
`market_sensitivity_max`	number	min 0, max 1	2 endpoints
`market_sensitivity_min`	number	min 0, max 1	2 endpoints
`near`	point	—	3 endpoints
`observed_end`	date_or_instant	—	5 endpoints
`observed_start`	date_or_instant	—	5 endpoints
`office`	enum `office_id`	—	4 endpoints
`office_as_of`	date	—	4 endpoints
`offset`	integer	Varies by endpoint; see below	15 endpoints
`propagation_potential_max`	number	min 0, max 1	2 endpoints
`propagation_potential_min`	number	min 0, max 1	2 endpoints
`q`	string	Varies by endpoint; see below	7 endpoints
`radius_km`	number	—	2 endpoints
`recorded_end`	string	—	4 endpoints
`recorded_start`	string	—	4 endpoints
`region`	enum `region`	—	12 endpoints
`scope`	enum `atlas_posture_scope`	Varies by endpoint; see below	2 endpoints
`scope_version`	string	—	4 endpoints
`search`	string	—	4 endpoints
`search_mode`	enum `reporting_search_mode`	default `semantic`	2 endpoints
`significance_max`	number	min 0, max 1	2 endpoints
`significance_min`	number	min 0, max 1	2 endpoints
`sort`	string	Varies by endpoint; see below	10 endpoints
`source`	enum `facility_source_silo`	Varies by endpoint; see below	2 endpoints
`source_actor_country`	enum `country`	case-insensitive	2 endpoints
`start_date`	date	—	2 endpoints
`status`	enum `facility_status`	case-insensitive	3 endpoints
`story_category`	enum `story_category`	—	2 endpoints
`subcategory`	csv	—	5 endpoints
`systemic_importance_max`	number	min 0, max 1	2 endpoints
`systemic_importance_min`	number	min 0, max 1	2 endpoints
`target_actor_country`	enum `country`	case-insensitive	2 endpoints
`time_basis`	enum `activity-time-basis`	default `published`	3 endpoints
`type`	enum `facility_type`	—	3 endpoints
`weighting`	enum `atlas_weighting`	default `attention`	2 endpoints
`window`	duration	Varies by endpoint; see below	3 endpoints

Aliases

Both spellings are accepted and mean exactly the same thing. The canonical name is what appears in applied_filters, whichever you sent.

Canonical	Also accepted
`as_of`	`realtime_start`, `vintage`
`branch`	`topic`
`category`	`categories`
`component`	`decompose`
`days`	`window`
`end_date`	`date_end`
`entities`	`entity_id`, `entity`
`entity_query`	`entity_search`, `entity_terms`, `numerator`
`entity_search`	`q`, `counterparty`
`geo`	`id`
`language`	`languages`
`languages`	`language`
`list`	`source`
`min_match_confidence`	`threshold`
`organization`	`organization_entity_id`, `org`
`publisher_country_iso3`	`publisher_country`
`search`	`q`
`start_date`	`date_start`
`variant`	`lens`

Deliberately rejected parameters

These return 400 rather than being silently ignored. A filter that looks accepted and does nothing is worse than one that fails loudly — it produces a confident, wrong answer.

Endpoint	Parameter	Code	Why	Instead
`/api/v2/events`	`fatalities_min`, `fatalities_max`, `min_fatalities`, `max_fatalities`, `fatalities`	`UNSUPPORTED_FILTER`	Fatality RANGE filters are not implemented on this endpoint. `fatalities` is also a CONFLICT-family observable — the CAMEO+ family has no such field and serves null — so a range filter would quietly exclude most of the corpus on top of that. Gate with `has_fatalities=true`, then threshold the `fatalities` field returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows, `/api/v2/events/summary` returns `fatalities` and `fatality_event_count` per bucket.	`has_fatalities=true`, `fatalities (response field — threshold client-side)`, `/api/v2/events/summary?group_by=country`
`/api/v2/events`, `/api/v2/events/summary`	`geo_scope`, `scope`, `detail`, `event_readiness`, `cluster_certainty`, `quad_class`	`UNSUPPORTED_FILTER`	This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.	—
`/api/v2/events`, `/api/v2/events/summary`	`as_of`	`UNSUPPORTED_PARAM`	Event metrics are computed live and are not vintaged, so as_of cannot return a reproducible point-in-time result here. Use observed_start / observed_end to bound by when an event was coded, or the Atlas (/api/v2/intelligence/) and macro (/api/v2/macro/) endpoints for true point-in-time reads.	`observed_start`, `observed_end`, `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/*?as_of=`
`/api/v2/stories`	`fatalities_min`, `fatalities_max`, `min_fatalities`, `max_fatalities`, `fatalities`	`UNSUPPORTED_FILTER`	Fatality RANGE filters are not implemented on this endpoint. `fatalities` is also a CONFLICT-family observable — the CAMEO+ family has no such field and serves null — so a range filter would quietly exclude most of the corpus on top of that. Gate with `has_fatalities=true`, then threshold the `fatalities` field returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows, `/api/v2/stories/summary` returns `fatalities` and `fatality_event_count` per bucket.	`has_fatalities=true`, `fatalities (response field — threshold client-side)`, `/api/v2/stories/summary?group_by=country`
`/api/v2/stories`, `/api/v2/stories/summary`	`geo_scope`, `scope`, `detail`, `event_readiness`, `cluster_certainty`, `total_events`	`UNSUPPORTED_FILTER`	This v2 endpoint does not support scope/detail/readiness/certainty/total_events selectors.	—
`/api/v2/stories`	`as_of`	`UNSUPPORTED_PARAM`	Stories retain their current settled representation, not every historical version. as_of therefore cannot reconstruct the Story, article set, entity links, or merge state 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.	`observed_start`, `observed_end`, `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/observations?as_of=`
`/api/v2/events/summary`	`search`	`UNSUPPORTED_FILTER`	search is only supported on list/search endpoints. Use /api/v2/events for semantic Event retrieval, then summarize with structured filters.	`/api/v2/events`
`/api/v2/events/summary`	`sort`	`UNSUPPORTED_PARAM`	sort orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/events to walk the underlying rows.	`/api/v2/events`, `limit`
`/api/v2/events/summary`	`cursor`	`UNSUPPORTED_PARAM`	cursor orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/events to walk the underlying rows.	`/api/v2/events`, `limit`
`/api/v2/events/summary`	`offset`	`UNSUPPORTED_PARAM`	offset orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/events to walk the underlying rows.	`/api/v2/events`, `limit`
`/api/v2/events/summary`	`include_images`	`UNSUPPORTED_PARAM`	include_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/events for rows with images.	`/api/v2/events`
`/api/v2/events/summary`	`include_entity_images`	`UNSUPPORTED_PARAM`	include_entity_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/events for rows with images.	`/api/v2/events`
`/api/v2/stories/summary`	`event_family`	`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.	`event_category`, `/api/v2/events/summary`
`/api/v2/stories/summary`	`search`	`UNSUPPORTED_FILTER`	search is only supported on list/search endpoints. Use /api/v2/stories for semantic Story retrieval, then summarize with structured filters.	`/api/v2/stories`
`/api/v2/stories/summary`	`sort`	`UNSUPPORTED_PARAM`	sort orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/stories to walk the underlying rows.	`/api/v2/stories`, `limit`
`/api/v2/stories/summary`	`cursor`	`UNSUPPORTED_PARAM`	cursor orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/stories to walk the underlying rows.	`/api/v2/stories`, `limit`
`/api/v2/stories/summary`	`offset`	`UNSUPPORTED_PARAM`	offset orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/stories to walk the underlying rows.	`/api/v2/stories`, `limit`
`/api/v2/stories/summary`	`include_images`	`UNSUPPORTED_PARAM`	include_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/stories for rows with images.	`/api/v2/stories`
`/api/v2/stories/summary`	`include_entity_images`	`UNSUPPORTED_PARAM`	include_entity_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/stories for rows with images.	`/api/v2/stories`
`/api/v2/stories/summary`	`as_of`	`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.	`observed_start`, `observed_end`, `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/observations?as_of=`
`/api/v2/facilities`	`admin1`	`UNSUPPORTED_FILTER`	Facilities carry no sub-national admin1 column. Filter by country / region / continent / bbox / near instead.	`country`, `region`, `continent`, `bbox`, `near`
`/api/v2/facilities/{facility_id}/context`	`as_of`	`UNSUPPORTED_PARAM`	Facility ownership is not vintaged — the directory records the latest known owner and prior owners are not yet reconstructable as-of, so an as_of result here would not be reproducible.	`/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/*?as_of=`
`/api/v2/screening/match`	`country`	`COUNTRY_FILTER_UNSUPPORTED`	screening/match is a name/id matcher, not a jurisdiction browser	`GET /api/v2/lists/entries?country=RUS`, `nationality= (evidence for a person screen)`
`/api/v2/screening/match`	`region`	`COUNTRY_FILTER_UNSUPPORTED`	screening/match is a name/id matcher, not a jurisdiction browser	`GET /api/v2/lists/entries?region=Europe`
`/api/v2/screening/match`	`continent`	`COUNTRY_FILTER_UNSUPPORTED`	screening/match is a name/id matcher, not a jurisdiction browser	`GET /api/v2/lists/entries?continent=Europe`
`/api/v2/entities`	`entity`	`UNSUPPORTED_FILTER`	This endpoint LISTS entities; it does not scope to one. `entity=` means “restrict to this entity’s coverage” on /api/v2/events and /api/v2/stories, and it cannot mean that here. For the entities that appear alongside one entity use `co_occurring_with=`; for one entity’s own record use `GET /api/v2/entities/{entity_id}`; for its coverage use `/api/v2/events?entity=` or `/api/v2/stories?entity=`. The handle is the same in all four.	`co_occurring_with=<handle>`, `GET /api/v2/entities/{entity_id}`, `GET /api/v2/events?entity=<handle>`, `GET /api/v2/stories?entity=<handle>`

Deprecated parameters

Still accepted, still returning the same rows — and no longer the way to express the filter. A code string we published is a contract, so these are added-and-superseded rather than renamed; nothing you have built will break. New code should use the replacement. These are the only place a deprecated parameter is listed: it no longer appears in the per-endpoint tables above, in the OpenAPI spec, or in the MCP tool schemas, so a new integration cannot pick one up by accident. See API stability for the notice period that applies before any of them stops working.

Endpoint	Parameter	Deprecated since	Use instead
`/api/v2/events`	`event_family`	2026-05	`category`
`/api/v2/events`	`domain`	2026-05	`category`
`/api/v2/stories`	`event_family`	2026-05	`category`
`/api/v2/stories`	`domain`	2026-05	`category`
`/api/v2/events/summary`	`event_family`	2026-05	`category`
`/api/v2/events/summary`	`domain`	2026-05	`category`
`/api/v2/stories/summary`	`domain`	2026-05	`category`
`/api/v2/entities`	`event_family`	2026-05	`category`
`/api/v2/entities`	`domain`	2026-05	`category`

Per-endpoint parameters

`GET /api/v2/activity`

12 accepted parameters — 10 core, 2 advanced.

Parameter	Type	Constraints	Description
`time_basis`	enum `activity-time-basis`	default `published`	Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged.
`date_start`	date	—	First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time.
`date_end`	date	—	Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day.
`hour`	integer	min 0, max 23	Optional UTC hour, 0–23. Requires a single date and rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day.
`country`	enum `country`	—	Known country attribution. Evidence distinguishes location, actor origin, reporting and source association.
`kind`	enum `activity-kind`	—	Published record type to include in activity evidence.
`change`	enum `activity-change`	—	Publication transition. Defaults to all substantive transitions.
`entity`	string	—	Selected entity ID from /api/v2/search; returns records linked to that identity.
`limit`	limit	min 1, max 100, default `25`	Number of publication records per page, from 1 to 100.
`cursor`	string	—	Opaque next_cursor from the previous response. Keep the other filters unchanged.

Advanced. Fully supported and applied exactly like the parameters above. They are separated because they answer specialist questions — a second time axis, directional actor geography, family-scoped metric bounds, and resolution modifiers whose defaults are what most callers want.

Parameter	Type	Constraints	Description
`recorded_start`	string	—	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.
`recorded_end`	string	—	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.

`GET /api/v2/countries`

15 accepted parameters.

Parameter	Type	Constraints	Description
`time_basis`	enum `activity-time-basis`	default `published`	Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged.
`date_start`	date	—	First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time.
`date_end`	date	—	Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day.
`hour`	integer	min 0, max 23	Optional UTC hour, 0–23. Requires a single date and rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day.
`country`	enum `country`	—	Known country attribution. Evidence distinguishes location, actor origin, reporting and source association.
`basis`	string	default `publication`	publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. Reporting has day precision and rejects hour.
`include_event_metrics`	boolean	—	Include Event metric maxima with tied-country evidence, five AI-coded metric averages with scored Event counts, and per-country readings/linked identity counts. Reporting basis only; occurrence-date and location scope. Averages weight each finite scored canonical Event equally, independently of directory pagination. Unrestricted world averages include unlocated Events; geographic filters use location. Goldstein remains a signed maximum only. No scored observations gives null/count 0; unavailable context remains null.
`include_context`	boolean	—	Include dated macro rollups for the selected geography, with same-period coverage and aggregation methods. Requires intelligence entitlement.
`directory`	boolean	—	Enumerate every registered country, including countries without observed activity; supports search, geography, sort and pagination.
`q`	string	—	Country directory name or ISO code search. Requires directory=true.
`region`	enum `region`	—	Registered region scope.
`continent`	enum `continent`	—	Registered continent scope.
`sort`	string	—	Directory order: name alphabetically (default in directory mode), events or stories descending with stable name ties. Requires directory=true.
`limit`	limit	min 1, max 250	Countries per directory page (default 25 in directory mode). Requires directory=true; otherwise this parameter is rejected.
`offset`	integer	min 0	Directory row offset (default 0 in directory mode). Requires directory=true.

`GET /api/v2/countries/{iso3}`

5 accepted parameters.

Parameter	Type	Constraints	Description
`time_basis`	enum `activity-time-basis`	default `published`	Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged.
`date_start`	date	—	First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time.
`date_end`	date	—	Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day.
`hour`	integer	min 0, max 23	Optional UTC hour, 0–23. Requires a single date and rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day.
`basis`	string	default `publication`	publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. Reporting has day precision and rejects hour.

`GET /api/v2/events`

52 accepted parameters — 24 core, 28 advanced.

Parameter	Type	Constraints	Description
`date_start`	date	—	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.
`date_end`	date	—	EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). For when we RECORDED it, use observed_end.
`days`	duration	—	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.
`limit`	limit	min 1, max 100, default `25`	Rows per page. Default 25, max 100.
`cursor`	cursor	—	Opaque pagination cursor taken from the previous response’s `pagination.next_cursor`.
`country`	csv	case-insensitive	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`.
`region`	enum `region`	—	One ACLED-style region. Expanded to its member countries.
`continent`	enum `continent`	—	One continent. Expanded to its member countries.
`admin1`	csv	—	State or province (admin1), not a city. Discover valid values with `GET /api/v2/geo/admin1?country=`.
`near`	point	—	Point proximity `lat,lon`, combined with `radius_km`. The box is used for index pruning and rows are refined by true great-circle distance.
`radius_km`	number	—	Radius in km for point proximity. Default 100, capped 2000.
`entity`	enum `entity_handle`	—	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.
`category`	enum `event_category`	case-insensitive	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.
`subcategory`	csv	—	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.
`significance_min`	number	min 0, max 1	Significance lower bound (0–1).
`significance_max`	number	min 0, max 1	Significance upper bound (0–1).
`search_mode`	enum `reporting_search_mode`	default `semantic`	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.
`search`	string	—	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.
`sort`	enum `sort`	default `significance`	Ranking. A bare `search` with no explicit sort ranks by relevance instead.
`has_fatalities`	boolean	—	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.
`civilian_targeting`	boolean	—	Restrict to events coded as targeting civilians.
`languages`	csv	—	Source-language filter (ISO 639-1/2) on the linked Story’s coverage.
`include_images`	boolean	default `false`	Attach article images to each card. Off by default. When enabled, entity thumbnails are also included unless `include_entity_images=false`.
`include_entity_images`	boolean	default `true`	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.

Parameter	Type	Constraints	Description
`recorded_start`	string	—	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.
`recorded_end`	string	—	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.
`observed_start`	date_or_instant	—	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.
`observed_end`	date_or_instant	—	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.
`country_match`	enum `country_match`	default `location_or_actor_origin`	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.
`bbox`	bbox	—	Bounding box `lat_min,lon_min,lat_max,lon_max`.
`source_actor_country`	enum `country`	case-insensitive	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.
`target_actor_country`	enum `country`	case-insensitive	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.
`actor_country`	enum `country`	case-insensitive	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.
`entity_match`	enum `entity_match`	default `coverage`	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.
`entity_family`	enum `entity_family`	default `expand`	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.
`office`	enum `office_id`	—	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.
`office_as_of`	date	—	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_min`	number	min 0, max 1	Confidence lower bound (0–1).
`confidence_max`	number	min 0, max 1	Confidence upper bound (0–1).
`goldstein_scale_min`	number	min -10, max 10	Goldstein scale lower bound (-10–10).
`goldstein_scale_max`	number	min -10, max 10	Goldstein scale upper bound (-10–10).
`magnitude_min`	number	min 0, max 10	Magnitude lower bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`magnitude_max`	number	min 0, max 10	Magnitude upper bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`systemic_importance_min`	number	min 0, max 1	Systemic importance lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`systemic_importance_max`	number	min 0, max 1	Systemic importance upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`propagation_potential_min`	number	min 0, max 1	Propagation potential lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`propagation_potential_max`	number	min 0, max 1	Propagation potential upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`market_sensitivity_min`	number	min 0, max 1	Market sensitivity lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`market_sensitivity_max`	number	min 0, max 1	Market sensitivity upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`geo_precision_min`	number	min 1, max 3	Geo precision lower bound (1–3).
`geo_precision_max`	number	min 1, max 3	Geo precision upper bound (1–3).
`include_total`	boolean	—	Add `pagination.estimated_total` — how many events match the filters, ignoring the page. Off by default because it costs a second scan of the same window. Counted from the SAME filters and the same row source as the page, so it always describes the result set you are walking. It is `null` (not a number) on a `search=` request: semantic retrieval is bounded by a candidate cap, so any total there would describe the candidate pool rather than the matching events. Without it, `pagination.next_cursor` still tells you whether more rows exist — non-null means yes, null means the walk is finished.

`GET /api/v2/stories`

35 accepted parameters — 25 core, 10 advanced.

Parameter	Type	Constraints	Description
`date_start`	date	—	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.
`date_end`	date	—	EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). For when we RECORDED it, use observed_end.
`days`	duration	—	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.
`limit`	limit	min 1, max 100, default `25`	Rows per page. Default 25, max 100.
`cursor`	cursor	—	Opaque pagination cursor taken from the previous response’s `pagination.next_cursor`.
`country`	csv	case-insensitive	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.
`region`	enum `region`	—	One ACLED-style region. Expanded to its member countries.
`continent`	enum `continent`	—	One continent. Expanded to its member countries.
`admin1`	csv	—	State or province (admin1), not a city. Discover valid values with `GET /api/v2/geo/admin1?country=`.
`entity`	enum `entity_handle`	—	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.
`category`	enum `event_category`	case-insensitive	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.
`subcategory`	csv	—	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.
`search_mode`	enum `reporting_search_mode`	default `semantic`	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.
`search`	string	—	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.
`story_category`	enum `story_category`	—	Story-level category. Comma-separate for OR.
`has_events`	boolean	—	Restrict to Stories that have (or have not) linked Events.
`has_fatalities`	boolean	—	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.
`civilian_targeting`	boolean	—	Restrict to Stories whose linked Events target civilians.
`article_count_min`	number	min 0	Minimum article count.
`article_count_max`	number	min 0	Maximum article count.
`languages`	csv	—	Coverage-language filter (ISO 639-1/2).
`include_images`	boolean	default `false`	Attach article images to each card. Off by default. When enabled, entity thumbnails are also included unless `include_entity_images=false`.
`include_entity_images`	boolean	default `true`	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.
`sort`	enum `sort`	default `significance`	Ranking.
`related`	boolean	—	Attach related Stories (schema 130).

Parameter	Type	Constraints	Description
`recorded_start`	string	—	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.
`recorded_end`	string	—	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.
`observed_start`	date_or_instant	—	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.
`observed_end`	date_or_instant	—	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.
`country_match`	enum `country_match`	default `location_or_actor_origin`	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.
`bbox`	bbox	—	Bounding box `lat_min,lon_min,lat_max,lon_max`.
`entity_match`	enum `entity_match`	default `coverage`	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.
`entity_family`	enum `entity_family`	default `expand`	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.
`office`	enum `office_id`	—	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.
`office_as_of`	date	—	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`.

`GET /api/v2/events/summary`

44 accepted parameters — 19 core, 25 advanced.

Parameter	Type	Constraints	Description
`date_start`	date	—	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.
`date_end`	date	—	EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). For when we RECORDED it, use observed_end.
`days`	duration	—	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.
`limit`	limit	min 1, max 500, default `50`	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.
`group_by`	enum `event_group_by`	default `date`	The dimension to aggregate over. Every dimension reconciles to the same total.
`country`	csv	case-insensitive	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`.
`region`	enum `region`	—	One ACLED-style region. Expanded to its member countries.
`continent`	enum `continent`	—	One continent. Expanded to its member countries.
`admin1`	csv	—	State or province (admin1), not a city. Discover valid values with `GET /api/v2/geo/admin1?country=`.
`near`	point	—	Point proximity `lat,lon`, combined with `radius_km`. The box is used for index pruning and rows are refined by true great-circle distance.
`radius_km`	number	—	Radius in km for point proximity. Default 100, capped 2000.
`entity`	enum `entity_handle`	—	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.
`category`	enum `event_category`	case-insensitive	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.
`subcategory`	csv	—	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.
`significance_min`	number	min 0, max 1	Significance lower bound (0–1).
`significance_max`	number	min 0, max 1	Significance upper bound (0–1).
`has_fatalities`	boolean	—	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.
`civilian_targeting`	boolean	—	Restrict to events coded as targeting civilians.
`languages`	csv	—	Coverage-language filter (ISO 639-1/2) on the underlying articles.

Parameter	Type	Constraints	Description
`observed_start`	date_or_instant	—	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.
`observed_end`	date_or_instant	—	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.
`country_match`	enum `country_match`	default `location_or_actor_origin`	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.
`bbox`	bbox	—	Bounding box `lat_min,lon_min,lat_max,lon_max`.
`source_actor_country`	enum `country`	case-insensitive	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.
`target_actor_country`	enum `country`	case-insensitive	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.
`actor_country`	enum `country`	case-insensitive	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.
`entity_match`	enum `entity_match`	default `coverage`	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.
`entity_family`	enum `entity_family`	default `expand`	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.
`office`	enum `office_id`	—	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.
`office_as_of`	date	—	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_min`	number	min 0, max 1	Confidence lower bound (0–1).
`confidence_max`	number	min 0, max 1	Confidence upper bound (0–1).
`goldstein_scale_min`	number	min -10, max 10	Goldstein scale lower bound (-10–10).
`goldstein_scale_max`	number	min -10, max 10	Goldstein scale upper bound (-10–10).
`magnitude_min`	number	min 0, max 10	Magnitude lower bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`magnitude_max`	number	min 0, max 10	Magnitude upper bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`systemic_importance_min`	number	min 0, max 1	Systemic importance lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`systemic_importance_max`	number	min 0, max 1	Systemic importance upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`propagation_potential_min`	number	min 0, max 1	Propagation potential lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`propagation_potential_max`	number	min 0, max 1	Propagation potential upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`market_sensitivity_min`	number	min 0, max 1	Market sensitivity lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`market_sensitivity_max`	number	min 0, max 1	Market sensitivity upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family.
`geo_precision_min`	number	min 1, max 3	Geo precision lower bound (1–3).
`geo_precision_max`	number	min 1, max 3	Geo precision upper bound (1–3).

`GET /api/v2/stories/summary`

28 accepted parameters — 20 core, 8 advanced.

Parameter	Type	Constraints	Description
`date_start`	date	—	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.
`date_end`	date	—	EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). For when we RECORDED it, use observed_end.
`days`	duration	—	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.
`limit`	limit	min 1, max 500, default `50`	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.
`group_by`	enum `story_group_by`	default `date`	The dimension to aggregate over. Country buckets overlap when country_attribution=all; use group_by=date for distinct totals.
`country_attribution`	enum `story_country_attribution`	default `primary`	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.
`country`	csv	case-insensitive	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.
`region`	enum `region`	—	One ACLED-style region. Expanded to its member countries.
`continent`	enum `continent`	—	One continent. Expanded to its member countries.
`admin1`	csv	—	State or province (admin1), not a city. Discover valid values with `GET /api/v2/geo/admin1?country=`.
`entity`	enum `entity_handle`	—	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.
`category`	enum `event_category`	case-insensitive	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.
`subcategory`	csv	—	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.
`story_category`	enum `story_category`	—	Story-level topic, comma-separated for OR. Distinct from the EVENT taxonomy that `category` filters.
`has_events`	boolean	—	Restrict to Stories with at least one linked Event.
`has_fatalities`	boolean	—	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.
`civilian_targeting`	boolean	—	Restrict to Stories with civilian-targeting events.
`article_count_min`	number	min 1	Lower bound on the number of source articles behind a Story.
`article_count_max`	number	min 1	Upper bound on the number of source articles behind a Story.
`languages`	csv	—	Coverage-language filter (ISO 639-1/2) on the underlying articles.

Parameter	Type	Constraints	Description
`observed_start`	date_or_instant	—	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.
`observed_end`	date_or_instant	—	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.
`country_match`	enum `country_match`	default `location_or_actor_origin`	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.
`bbox`	bbox	—	Bounding box `lat_min,lon_min,lat_max,lon_max`.
`entity_match`	enum `entity_match`	default `coverage`	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.
`entity_family`	enum `entity_family`	default `expand`	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.
`office`	enum `office_id`	—	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.
`office_as_of`	date	—	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`.

`GET /api/v2/facilities`

19 accepted parameters.

Parameter	Type	Constraints	Description
`limit`	limit	min 1, max 100, default `25`	Rows per page. Default 25, max 100.
`cursor`	cursor	—	Opaque pagination cursor taken from the previous response’s `pagination.next_cursor`.
`granularity`	string	default `site`	`site` (default) returns one canonical physical site; `unit` exposes source registry units.
`q`	string	—	Case-insensitive substring match over `name`. This is NOT semantic search — nothing is embedded, and a conceptually related term that does not appear literally will not match. Results are ordered by facility name (A–Z), not by relevance, so a query matching more rows than `limit` returns an arbitrary slice.
`type`	enum `facility_type`	—	Facility type (21 values). Comma-separate for OR.
`class`	enum `facility_class`	—	Broad facility class; expanded to its member types.
`source`	enum `facility_source_silo`	—	Source silo the facility was projected from.
`status`	enum `facility_status`	case-insensitive	Lifecycle status. Matched case-insensitively — the corpus carries both `operating` and `Operating` — and GEM’s ”- inferred N y” variants fold into their base state. This is an OBSERVED vocabulary measured from the directory, not a closed list.
`country`	csv	case-insensitive	Country filter (ISO-3). `region` and `continent` expand to their member countries. A facility matches on either its primary or secondary country.
`region`	enum `region`	—	Region; expanded to member countries.
`continent`	enum `continent`	—	Continent; expanded to member countries.
`entity`	enum `entity_handle`	—	Owner filter. An `e_` spine id matches the resolved owner exactly; a name falls back to a fuzzy match on owner names.
`capacity_mw_min`	number	min 0	Minimum capacity in MW. Capacity units differ per tracker — see the tracker reference.
`capacity_mw_max`	number	min 0	Maximum capacity in MW.
`has_geo`	boolean	—	Restrict to facilities that do (or do not) carry coordinates. 99.15% of the directory does; the residual are GEM linear/areal assets — pipelines and fields — which are geometry, not a point.
`has_owner`	boolean	—	`true` restricts to facilities with a SPINE-RESOLVED owner (`owners[].entity_id` non-null). A facility can carry an unresolved owner NAME and still be excluded — that is the documented meaning of “owner” here, and it is the resolved id that makes owner-bridge fusion and `entity=` chaining possible. Owner coverage is 47.1% overall: heavy industry 99.9%, AI data centers 85%, GEM power 43%, ports 0% (WPI publishes no ownership layer).
`sort`	string	—	Ordering: name · capacity_desc · capacity_asc · recent · country.
`bbox`	bbox	—	Bounding box `lat_min,lon_min,lat_max,lon_max`.
`near`	point	—	Point proximity `lat,lon,radius_km`, refined by true great-circle distance. Note this is the three-part grammar — /api/v2/events takes `near=lat,lon` with a separate `radius_km`.

`GET /api/v2/facilities/{facility_id}`

Takes no query parameters.

`GET /api/v2/facilities/{facility_id}/units`

Takes no query parameters.

`GET /api/v2/facilities/{facility_id}/context`

5 accepted parameters.

Parameter	Type	Constraints	Description
`days`	duration	default `30`	Owner-coverage window in days, max 30.
`date_start`	date	—	Explicit start of the owner-coverage window.
`date_end`	date	—	Explicit end of the owner-coverage window.
`limit`	limit	min 1, max 50, default `10`	Maximum owner events to attach. Default 10, max 50.
`include`	enum `facility_context_include`	—	Optional extra blocks. `gov` attaches the owner’s federal-award / FARA / sanctions footprint. An unentitled plan degrades the block to null with a `sources_unavailable` entry — it never 403s the whole response.

`GET /api/v2/intelligence/gpr`

15 accepted parameters.

Parameter	Type	Constraints	Description
`construction`	enum `atlas_gpr_construction`	default `own_coverage`	Index construction. `world_corpus` is the count-weighted GPR reference and accepts only variant=gpr, metric=gpr, and weighting=attention.
`variant`	enum `atlas_gpr_variant`	—	GPR lens. `lens` is the legacy alias. Defaults to `gpr` for world_corpus and `events` otherwise.
`component`	enum `atlas_gpr_component`	default `all`	Variant-scoped decomposition component. `decompose` is the legacy alias.
`metric`	enum `atlas_gpr_metric`	default `gpr`	Returned GPR measure.
`weighting`	enum `atlas_weighting`	default `attention`	Aggregate weighting.
`level`	enum `atlas_level`	default `world`	Geographic aggregation level.
`geo`	string	—	Place identifier appropriate for `level`; `id` is the legacy alias.
`window`	duration	min 1, max 30	Trailing display window in days, 1–30. Defaults to 7 only when no explicit dates are supplied; omit when sending date_start/date_end.
`date_start`	date	—	First observation date.
`date_end`	date	—	Last observation date.
`date`	date	—	One observation date; overrides the range.
`as_of`	date	—	Point-in-time vintage. `realtime_start` and `vintage` are aliases.
`limit`	limit	min 1, max 100, default `100`	Maximum observations returned.
`cursor`	cursor	—	Pagination cursor.
`offset`	integer	min 0	Legacy numeric pagination offset.

`GET /api/v2/intelligence/posture`

8 accepted parameters.

Parameter	Type	Constraints	Description
`country`	string	—	Country ISO3 shortcut. Takes precedence over geo.
`level`	enum `atlas_level`	default `country`	Geographic level. Defaults to country.
`geo`	string	—	Country ISO3, region or continent name. Required unless country is supplied or level=world.
`scope`	enum `atlas_posture_scope`	default `all`	Optional dynamic evidence scope. Omission returns all scopes.
`window`	enum `atlas_posture_window`	default `30d`	Duration of the dynamic Event window.
`weighting`	enum `atlas_weighting`	default `attention`	Aggregate weighting. A country is not a rollup; response discloses any fallback.
`date`	date	—	Window end date. Omission uses the latest computed observations.
`as_of`	date	—	Observation vintage cutoff. Structural inputs and normalization are not a historical snapshot; inspect response limitations.

`GET /api/v2/intelligence/coverage`

4 accepted parameters.

Parameter	Type	Constraints	Description
`window`	duration	min 1, max 30, default `30`	Trailing coverage-measurement window in days, 1–30, ending today. Both `30` and `30d` are accepted, so the same spelling works here and on `/api/v2/intelligence/posture`.
`tier`	enum `atlas_coverage_tier`	case-insensitive	Return only countries in this coverage tier. `depth` = dense enough for a country-level Posture reading (the curated servable set); `thin` = some coverage but below that floor; `none` = no coded events in the window at all.
`region`	string	—	Return only countries in this region, matched case-insensitively against the region name each row carries.
`continent`	string	—	Return only countries on this continent, matched case-insensitively against the continent name each row carries.

`GET /api/v2/filings/resolve`

5 accepted parameters.

Parameter	Type	Constraints	Description
`q`	string	—	Company-name query. `name` and `search` are aliases.
`ticker`	identifier	—	Exact ticker symbol.
`cik`	identifier	—	SEC CIK, with or without zero padding.
`limit`	limit	min 1, max 100, default `10`	Maximum candidates returned.
`min_score`	number	min 0, max 1	Minimum fuzzy-name candidate score.

`GET /api/v2/screening/match`

8 accepted parameters.

Parameter	Type	Constraints	Description
`q`	string	—	Counterparty name. `name` is an alias.
`id`	identifier	—	Strong entity or list identifier.
`as_of`	date	—	Historical list-membership date.
`min_match_confidence`	number	min 0, max 1, default `0.85`	Minimum returned match confidence. `threshold` is the deprecated alias.
`include_exposure`	boolean	default `true`	Attach ownership-chain exposure context.
`limit`	limit	min 1, max 100, default `25`	Maximum matched entities returned.
`nationality`	csv	—	Nationality / citizenship of the subject as ISO-3 codes, comma-separated (`IRN,IRQ`). Evidence only: compared against each candidate’s `country_iso3` and reported per candidate as `evidence.nationality` (`match` \| `mismatch` \| `unknown`); it never filters retrieval and never rejects on its own, because list country fields are inconsistently populated (see the coverage warning on /api/v2/lists/entries). An unresolvable code returns `400 INVALID_COUNTRY`.
`birth_year`	integer	min 1900	Year of birth of the subject (1900 to the current year). Evidence only, compared with a ±1 tolerance because lists publish approximate and circa dates: a candidate whose recorded year contradicts it beyond that tolerance is moved to `rejected_candidates` with `decision_evidence: birth_year_mismatch`; agreement is reported as `evidence.birth_year: match` and raises confidence only together with an exact name; a candidate with no recorded year is `unknown` and remains a candidate. There is deliberately NO date-of-birth parameter: the served person field is a birth YEAR (schema 171 stores year only, never a date), so a full DOB could not be compared to anything and would only invite callers to send PII we do not hold.

`GET /api/v2/exposure`

17 accepted parameters.

Parameter	Type	Constraints	Description
`lens`	enum `exposure_lens`	default `sanctions`	Exposure lens.
`subject`	enum `exposure_subject`	default `assets`	Result unit.
`country`	csv	—	Country filter.
`region`	string	—	Region expanded to countries.
`continent`	string	—	Continent expanded to countries.
`tracker`	csv	—	GEM tracker filter.
`list`	enum `exposure_list`	—	Contributing restricted-party list. `source` is an alias.
`min_stake_pct`	number	min 0, max 100	Minimum effective ownership-chain stake.
`direct_only`	boolean	—	Restrict to direct exposure.
`entity`	entity	—	Resolved entity identifier. `entity_id` is an alias.
`entity_search`	string	—	Fuzzy entity resolver query. `q` and `counterparty` are aliases.
`gem_id`	identifier	—	GEM asset identifier.
`group_by`	enum `exposure_group_by`	default `none`	Aggregation dimension.
`sort`	enum `exposure_sort`	default `capacity_desc`	Result ordering.
`limit`	limit	min 1, max 100, default `25`	Maximum rows returned.
`cursor`	cursor	—	Pagination cursor.
`offset`	integer	min 0	Legacy numeric offset.

19 accepted parameters.

Parameter	Type	Constraints	Description
`query`	string	—	Semantic denominator query.
`topic`	string	—	Lexical denominator topic.
`category`	string	—	Story or event category denominator.
`country`	string	—	Country denominator. Accepts an English name, ISO-2, or ISO-3. A Story matches when its own attributed countries include the value, or a linked Event is located there, or either linked Event actor originates there.
`region`	string	—	Region denominator.
`continent`	string	—	Continent denominator.
`languages`	csv	—	Language-code denominator.
`source_set`	csv	—	Source denominator. `all` selects the complete served Story corpus in the requested window; otherwise pass one or more article domains such as `reuters.com`.
`entities`	csv	—	Entity identifiers. `entity_id` and `entity` are singular compatibility aliases.
`entity_query`	string	—	Entity-name resolver input. `entity_search`, `entity_terms`, and `numerator` are aliases.
`run_id`	identifier	—	Previously materialized analytics run.
`denominator_hash`	identifier	—	Previously computed denominator identity.
`start_date`	date	—	First occurrence date. `date_start` is an alias.
`end_date`	date	—	Last occurrence date. `date_end` is an alias.
`date`	date	—	Single occurrence date.
`days`	duration	—	Trailing window. `window` is an alias.
`limit`	limit	min 1, max 100, default `25`	Maximum entity rows.
`cursor`	cursor	—	Pagination cursor.
`offset`	integer	min 0	Legacy numeric offset.

`GET /api/v2/stories/{story_id}/articles`

10 accepted parameters.

Parameter	Type	Constraints	Description
`start_date`	date	—	First Story partition date. `date_start` is an alias.
`end_date`	date	—	Last Story partition date. `date_end` is an alias.
`date`	date	—	Single Story partition date.
`days`	duration	default `14`	Trailing date window. `window` is an alias.
`limit`	limit	min 1, max 100, default `25`	Maximum articles returned.
`cursor`	cursor	—	Pagination cursor.
`offset`	integer	min 0	Legacy numeric offset.
`include_images`	boolean	—	Attach resolved article images.
`language`	csv	—	Origin language filter. `languages` is an alias.
`publisher_country_iso3`	string	—	Known publisher-country filter. `publisher_country` is an alias; unknown publishers are never guessed.

`GET /api/v2/lists`

4 accepted parameters.

Parameter	Type	Constraints	Description
`source`	enum `list_source_key`	case-insensitive	Restrict the catalogue to one `source_key`. Case-insensitive. The accepted set grows as sources are ingested: the values published here are the snapshot at build time, and `/api/v2/lists` (rows with `ingested: true`) is the live list.
`category`	enum `list_category`	case-insensitive	Return only sources of this kind. `sanctions` and `export_control` are the two categories that count toward the `sanctions` exposure lens; `debarment`, `wanted`, `maritime` and `domestic_terror` are catalogued and screenable but are not sanctions.
`jurisdiction`	string	—	Issuer jurisdiction code (`US`, `EU`, `UN`, `GB`, `CN`, `AU`, …), matched case-insensitively.
`cadence`	enum `list_cadence`	—	Our refresh cadence for the source. Observed vocabulary — matched exactly, case-sensitively.

`GET /api/v2/lists/entries`

14 accepted parameters.

Parameter	Type	Constraints	Description
`list`	enum `list_source_key`	case-insensitive	The list to search, by `source_key`. `source` is an alias. Case-insensitive. The accepted set grows as sources are ingested: the values published here are the snapshot at build time, and `/api/v2/lists` (rows with `ingested: true`) is the live list.
`q`	string	—	Case-insensitive substring over the entry name, its normalized form and every alias. `search` is an alias.
`country`	string	—	Country of the entry — a name, ISO-2 or ISO-3. `country_iso3` is an alias. Matched on the structured field OR the trailing ISO-2 token of an address, see `coverage_warning`.
`region`	string	—	Region expanded to its countries (`Eastern Europe`).
`continent`	string	—	Continent expanded to its countries (`Asia`).
`program`	string	—	Sanctions programme code, matched case-insensitively (`UKRAINE-EO13662`).
`entity`	entity	—	Only entries resolved to this entity — an `e_` spine id or a `wiki:` news id, collapsed through the arbiter. `entity_id` is an alias. An id the registry has never heard of answers `400 UNRESOLVED_ENTITY_ID` rather than an empty list.
`active_on`	date	—	Point-in-time: entries on the list on this date, by our observation history. A date outside `coverage_window` answers `screen_status: inconclusive` with the window, never an empty list.
`added_since`	date	—	Only entries first observed on or after this date. Ignored when `active_on` or `removed_since` is set.
`removed_since`	date	—	Only entries that LEFT a list on or after this date (`active: false`).
`sort`	enum `list_entries_sort`	default `name`	`name` (A–Z) or `recent` (latest observation first).
`limit`	limit	min 1, max 100, default `25`	Maximum entries returned.
`cursor`	cursor	—	Pagination cursor from `pagination.next_cursor`.
`offset`	integer	min 0	Legacy numeric offset; `cursor` is preferred.

`GET /api/v2/lists/changes`

9 accepted parameters.

Parameter	Type	Constraints	Description
`list`	enum `list_source_key`	case-insensitive	Restrict the feed to one list. `source` is an alias. Case-insensitive. The accepted set grows as sources are ingested: the values published here are the snapshot at build time, and `/api/v2/lists` (rows with `ingested: true`) is the live list.
`change_type`	enum `list_change_type`	—	`added`, `removed` or `changed`.
`date`	date	—	One snapshot date; with `days` it ends the trailing span on that date.
`date_start`	date	—	First snapshot date of an explicit window. `start_date` is an alias.
`date_end`	date	—	Last snapshot date of an explicit window. `end_date` is an alias.
`days`	duration	min 1, max 30	Trailing window in snapshot days, 1–30. `window` is an alias; `7` and `7d` are both accepted.
`limit`	limit	min 1, max 200, default `50`	Maximum change rows returned.
`cursor`	cursor	—	Pagination cursor from `pagination.next_cursor`.
`offset`	integer	min 0	Legacy numeric offset; `cursor` is preferred.

`GET /api/v2/meta/enums`

Takes no query parameters.

`GET /api/v2/meta/endpoints`

1 accepted parameter.

Parameter	Type	Constraints	Description
`endpoint`	string	—	Return one endpoint instead of all of them. Accepts either the descriptor id (`events-list`) or the path (`/api/v2/events`). An unknown value returns `404 NOT_FOUND` with the available ids in `details.available`.

`GET /api/v2/meta/query-units`

Takes no query parameters.

`GET /api/v2/search`

12 accepted parameters.

Parameter	Type	Constraints	Description
`sort`	string	—	Use name for stable alphabetical public-official browsing with universe=osint and holds_office=true. Default when q is absent.
`offset`	integer	min 0	Continue alphabetically sorted public officials using pagination.next_offset.
`q`	string	min 1, max 200	Canonical search text: a name, alias, or acronym. Required except when browsing public officials with universe=osint and holds_office=true. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names.
`type`	enum `search_entity_type`	—	Optional identity type used to narrow ambiguous candidates. Conflicting linked types retain entity_type=entity and type_evidence; a filtered result includes a conflict only when the requested type is a published possibility. facility searches the existing facility directory and returns facility_id, not an invented entity ID. Source entitlements apply.
`country`	csv	—	Known country association from source records, not an assertion of headquarters, citizenship, or reporting location. Accepts country names, ISO-2 or ISO-3; comma-separate for OR. Use country_match=strict for candidates with known matching evidence.
`country_match`	enum `search_country_match`	—	strict requires known matching source country association; include_unknown also returns candidates with no country evidence. Recommended requests explicitly send strict. Omission retains include_unknown compatibility.
`region`	enum `region`	—	Narrow source country associations by region; country_match controls unknown association.
`continent`	enum `continent`	—	Narrow source country associations by continent; country_match controls unknown association.
`include_images`	boolean	—	Include available entity portraits/logos. Unknown images stay null.
`limit`	limit	min 1, max 50, default `10`	Maximum number of ranked candidates to return.
`universe`	enum `search_universe`	default `all`	Search all merged entities, news entities, reference entities, raw GLEIF registry records, or OSINT list and office-holder records. The registry and osint lanes return source records with nullable entity_id; they do not establish news coverage. Source entitlements apply.
`holds_office`	boolean	—	Only politicians: entities that hold or have held a published public office (`sources.offices`), or on `universe=osint` only office-holder records. A ROLE filter, not a type — an office-holder is a `person`. Requires `can_use_offices` (403 PLAN_REQUIRED otherwise) and is not applicable to `universe=registry` (legal entities only; 400).

`GET /api/v2/situations`

15 accepted parameters.

Parameter	Type	Constraints	Description
`entity`	string	—	Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days.
`story_id`	string	—	Only Situations containing this currently served Story.
`event_uid`	string	—	Only Situations containing a served Story linked to this coded Event.
`include_map`	boolean	default `false`	Include country aggregates over every matching Situation, independently of page size. Requires a reporting window of at most 30 days.
`date_start`	date	—	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.
`date_end`	date	—	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.
`search`	string	—	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}`.
`min_stories`	integer	min 0, max 4294967295	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.
`min_articles`	integer	min 0, max 4294967295	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`.
`min_events`	integer	min 0, max 4294967295	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.
`sort`	enum `situation_sort`	default `recent`	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.
`limit`	limit	min 1, max 200, default `25`	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.
`offset`	integer	min 0, default `0`	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.
`country`	enum `country`	—	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.
`category`	enum `event_category`	—	Any member-linked coded Event in this Event taxonomy category, not Story category or a primary Situation label. Requires both reporting date bounds, at most 30 days. Country and category match the same Event.

`GET /api/v2/situations/{story_id}`

7 accepted parameters.

Parameter	Type	Constraints	Description
`date_start`	date	—	Earliest member date to include. Defaults to seven days before the anchor Story’s own date — not to today, because a situation is anchored on a Story, not on the request clock. On a curated Situation it filters the stored membership and `coverage` is re-derived from the members that survived, so the window reported is never wider than the payload.
`date_end`	date	—	Latest member date to include. Defaults to seven days after the anchor Story’s own date. The span may not exceed 30 days when both bounds are sent — the same ceiling the service compares against, not a number typed into a sentence. On a curated Situation, sending neither bound returns the whole stored span; sending one leaves the other side open.
`limit`	limit	min 1, max 200, default `50`	How many member Stories to return. The per-day rollup, the incidents and every total always describe the WHOLE situation, so a small page never shrinks the numbers.
`depth`	integer	min 1, max 3, default `1`	How many adjudicated hops out from the anchor to walk. `depth=1` returns only Stories a judge compared with the anchor DIRECTLY. Higher values reach further across time — no link in the source spans more than two days, so a week is depth, not distance — but a Story at hop 2 or 3 was never compared with the anchor itself: it was reached along a path of individually adjudicated edges, which `edges` and each Story’s `hop` and `via_story_id` make explicit. Treat depth > 1 as reachability, not membership. NOT APPLICABLE on a curated Situation, whose membership was adjudicated rather than traversed: there is no frontier, so the value appears under `applied_filters.ignored` beside `meta.situation_source: "curated"` rather than being echoed back as honoured.
`max_nodes`	integer	min 1, max 250, default `250`	Ceiling on member Stories. On a walked situation it bounds the frontier, ordered largest-first so a cut is reproducible rather than dependent on row order. On a curated one it bounds the membership read, taking them in the order `stories` is served in — earliest date first, largest within a date — so the cut is the head of the list you would have paged through rather than an arbitrary slice. `truncated` and `caps.members` say whether it bit, both measured. It is a FILTER, not a page size: the totals describe the members it admitted, while `limit` pages those members without changing any number.
`include`	enum `situation_include`	—	Optional blocks. `edges` returns one undirected row per adjudicated pair across the bounded graph membership, independently of Story pagination (`limit` and `offset`). An edge can reference a Story outside the returned page; fetch the member pages to hydrate those IDs and inspect `caps` and `scopes` for coverage. `/connections` pages membership provenance, not pairwise edges. Edges are omitted by default; `totals.edge_count` reports all pairs in the selected scope even when the returned graph is capped.
`offset`	integer	min 0, default `0`	Member Stories to skip. The member list is ordered by date then article count.

`GET /api/v2/situations/{story_id}/entities`

6 accepted parameters.

Parameter	Type	Constraints	Description
`scope_version`	string	—	Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages.
`date_start`	date	—	Optional earliest member reporting date. Omit both dates for the full servable membership.
`date_end`	date	—	Optional latest member reporting date. No implicit first200-member truncation.
`entity_type`	string	—	Case-insensitive type from summary.by_type (person, organization, company, ministry, agency, regulator, party, ngo, union, campaign, armed_group, brand, place, location, other); `unknown` selects untyped entities. A value outside that set is refused with 400 INVALID_ENUM rather than answered as an empty page. Applied after identity folding and echoed in applied_filters.
`limit`	limit	min 1, max 200, default `25`	Maximum linked entities returned per page.
`offset`	integer	min 0, default `0`	Entities to skip after canonical folding and type filtering. Stable order: distinct Story breadth, mentions, entity ID.

`GET /api/v2/situations/{story_id}/stories`

5 accepted parameters.

Parameter	Type	Constraints	Description
`scope_version`	string	—	Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages.
`date_start`	date	—	Optional earliest member reporting date. Omit both dates for the full servable membership.
`date_end`	date	—	Optional latest member reporting date. No implicit first200-member truncation.
`limit`	limit	min 1, max 100, default `25`	Records per page; independent of graph limits.
`offset`	integer	min 0, default `0`	Records to skip in this list. Stories order by reporting date, article count, ID; Events by significance then ID.

`GET /api/v2/situations/{story_id}/events`

5 accepted parameters.

Parameter	Type	Constraints	Description
`scope_version`	string	—	Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages.
`date_start`	date	—	Optional earliest member reporting date. Omit both dates for the full servable membership.
`date_end`	date	—	Optional latest member reporting date. No implicit first200-member truncation.
`limit`	limit	min 1, max 100, default `25`	Records per page; independent of graph limits.
`offset`	integer	min 0, default `0`	Records to skip in this list. Stories order by reporting date, article count, ID; Events by significance then ID.

`GET /api/v2/situations/{story_id}/connections`

5 accepted parameters.

Parameter	Type	Constraints	Description
`scope_version`	string	—	Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages.
`date_start`	date	—	Optional earliest member reporting date. Omit both dates for the full servable membership.
`date_end`	date	—	Optional latest member reporting date. No implicit first200-member truncation.
`limit`	limit	min 1, max 100, default `25`	Records per page; independent of graph limits.
`offset`	integer	min 0, default `0`	Records to skip in this list. Stories order by reporting date, article count, ID; Events by significance then ID.

`POST /api/v2/situations`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`GET /api/v2/entities`

23 accepted parameters — 18 core, 5 advanced.

Parameter	Type	Constraints	Description
`date_start`	date	—	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.
`date_end`	date	—	EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). For when we RECORDED it, use observed_end.
`days`	duration	—	Calendar-date window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. When omitted, entity coverage uses the last 30 calendar days with an observed-time bound over the same span. 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.
`limit`	limit	min 1, max 100, default `25`	Rows per page. Default 25, max 100.
`cursor`	cursor	—	Opaque pagination cursor taken from the previous response’s `pagination.next_cursor`.
`co_occurring_with`	enum `entity_handle`	—	Return the entities that appear ALONGSIDE this one — the entities linked to the same Stories, over the same window, narrowed by every other filter on this endpoint. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the same arbiter as `entity=` on `/api/v2/events` and `/api/v2/stories`, so one handle means the same entity everywhere. The subject is never returned in its own results. Co-occurrence is measured over SHARED STORIES — appearing in the same coverage, which is not a claim that the two entities interacted. A handle that resolves to nothing returns an EMPTY list with a `linkage` reason in `applied_filters`, never the global top entities.
`country`	csv	case-insensitive	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`.
`region`	enum `region`	—	One ACLED-style region. Expanded to its member countries.
`continent`	enum `continent`	—	One continent. Expanded to its member countries.
`category`	enum `event_category`	case-insensitive	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.
`subcategory`	csv	—	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.
`type`	enum `entity_type`	—	Restrict to one entity type. `entity_type` is accepted as an alias because that is the id `/meta/enums` publishes for this vocabulary.
`search`	string	—	Entity NAME to resolve. Matched across every entity universe and ranked by match quality (exact name, exact alias, acronym, prefix, fuzzy) before coverage — see each row’s `match_type` and `match_reason`. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names.
`languages`	enum `coverage_language`	—	ISO source-language filter. Restricts coverage metrics to articles in those languages.
`has_fatalities`	boolean	—	Restrict to entities linked to fatal events.
`civilian_targeting`	boolean	—	Restrict to entities linked to events coded as civilian targeting.
`sort`	enum `sort`	default `significance`	recent orders the bounded candidate page by candidate news-activity date (latest_observed_news_date, day precision), breaking same-day ties by candidate mention volume, then article volume, then stable identity; registry or link processing times do not lead. With significance, search resolves by match quality first. Explicit recent preserves this order even with search or taxonomy filters; resolved counts and latest_date do not reorder its fixed candidate page. Quiet rows may shorten a page; follow next_cursor even after an empty page.
`include_images`	boolean	—	Attach Wikipedia thumbnail/avatar URLs where available. Off unless requested — the images cost an extra lookup.

Parameter	Type	Constraints	Description
`recorded_start`	string	—	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.
`recorded_end`	string	—	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.
`observed_start`	date_or_instant	—	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.
`observed_end`	date_or_instant	—	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.
`country_match`	enum `country_match`	default `location_or_actor_origin`	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.

`GET /api/v2/entities/{entity_id}/dossier`

2 accepted parameters.

Parameter	Type	Constraints	Description
`as_of`	date	—	Date-filtered dossier: ingredients are filtered to facts dated on or before this date; offices use the office start/end dates the source publishes. Identity and attribution still use current knowledge, so meta.no_lookahead remains false. Absent = current knowledge. A past date needs `can_use_asof`. The three aliases are the spellings `resolveAsOf` honours everywhere else.
`event_days`	integer	min 1, max 30, default `30`	Trailing calendar window including the end date, in days (1–30). `summary.events_in_window` and `summary.stories_in_window` count coded occurrences and coverage Stories separately using the public serving summaries; the Event timeline preview is capped at 15.

`GET /api/v2/offices`

11 accepted parameters.

Parameter	Type	Constraints	Description
`limit`	limit	min 1, max 100, default `25`	Rows per page. Default 25, max 100.
`cursor`	cursor	—	Opaque pagination cursor taken from the previous response’s `pagination.next_cursor`.
`include_facets`	boolean	default `false`	Include complete country facets over the served office registry, independent of pagination and country/name filters. Holder counts are terms across offices, not distinct people. Null facets mean unavailable.
`country`	enum `country`	case-insensitive	Country of the office (ISO-3, ISO-2, or a name; comma-separate for OR). IGO / supranational posts carry no country and never match a country filter — use `scope=international` for those.
`scope`	enum `office_scope`	case-insensitive	Level of government: `national`, `subnational` (state / province / municipality) or `international` (IGO and supranational posts). Derived from the source’s topics; an office with no scope topic is `national`.
`branch`	enum `office_branch`	case-insensitive	Branch of government. `head` (head of state / government) wins over `executive` when a office carries both topics. `other` is sendable and returns the offices whose topics name no recognised branch.
`organization`	string	—	The legislature / ministry / court the office belongs to. A spine `e_…` id matches the resolved organization exactly (the arbiter family, so a merged-away alias still matches); any other value is a case-insensitive substring match on the organization name as published.
`q`	string	—	Case-insensitive substring match over the office `name`. This is NOT semantic search — nothing is embedded, and a conceptually related term that does not appear literally will not match. Results keep the `sort` order, not a relevance ranking, so a query matching more rows than `limit` returns the first page of that order — narrow with `country`.
`has_holders`	boolean	—	`true` restricts to offices with at least one office-holder on record (any status); `false` to offices we know only as an office, with nobody recorded in it. This counts office_holders, not asserted currency — an office whose only holders are `status: unknown` still has holders.
`as_of`	date	—	VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the `can_use_asof` gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — `meta.undated_office_holders` counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”.
`sort`	enum `offices_sort`	default `name`, case-insensitive	Ordering: `name` (default) · `holders_desc` · `country`.

`GET /api/v2/offices/{office_id}`

1 accepted parameter.

Parameter	Type	Constraints	Description
`as_of`	date	—	VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the `can_use_asof` gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — `meta.undated_office_holders` counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”.

`GET /api/v2/offices/{office_id}/holders`

4 accepted parameters.

Parameter	Type	Constraints	Description
`limit`	limit	min 1, max 200, default `50`	Rows per page. Default 50, max 200.
`cursor`	cursor	—	Opaque pagination cursor taken from the previous response’s `pagination.next_cursor`.
`status`	enum `office_holder_status`	case-insensitive	Restrict to office-holders the PUBLISHER asserts as `current`, `ended` or `unknown`. `unknown` is a real bucket, not a synonym for current: the source did not say, and nothing here infers currency from a missing `end_date`. Combine with `as_of` to ask “current AND in office on that date” — the two are independent predicates.
`as_of`	date	—	VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the `can_use_asof` gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — `meta.undated_office_holders` counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”.

`GET /api/v2/entities/{entity_id}/offices`

3 accepted parameters.

Parameter	Type	Constraints	Description
`status`	enum `office_holder_status`	case-insensitive	Restrict to office-holders the PUBLISHER asserts as `current`, `ended` or `unknown`. `unknown` is a real bucket, not a synonym for current: the source did not say, and nothing here infers currency from a missing `end_date`. Combine with `as_of` to ask “current AND in office on that date” — the two are independent predicates.
`as_of`	date	—	VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the `can_use_asof` gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — `meta.undated_office_holders` counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”.
`limit`	limit	min 1, max 200, default `100`	Maximum office-holders to return. Default 100, max 200; `truncated: true` when the entity has more.

`GET /api/v2/geo/admin1`

5 accepted parameters.

Parameter	Type	Constraints	Description
`country`	string	required	Country to enumerate admin1 (state/province) values for — required. Accepts a country name (`France`), ISO-2 (`FR`), or ISO-3 (`FRA`); an unresolvable or missing value returns `400 INVALID_COUNTRY`.
`days`	duration	min 1, max 30, default `30`	Trailing window in days (1–30) the region counts are measured over, ending today unless `date` moves the anchor. Both `7` and `7d` are accepted. The window actually used is echoed as `window_days` and in `applied_filters`.
`date`	date	—	Anchor date for the window. Alone it selects that single day; combined with `days` it ends the trailing span on that date.
`date_start`	date	—	First day of an explicit window. May not be combined with `days`/`window`.
`date_end`	date	—	Last day of an explicit window. May not be combined with `days`/`window`.

`GET /api/v2/monitors`

Takes no query parameters.

`POST /api/v2/monitors`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`GET /api/v2/monitors/{id}`

Takes no query parameters.

`PATCH /api/v2/monitors/{id}`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`DELETE /api/v2/monitors/{id}`

Takes no query parameters.

`POST /api/v2/monitors/preview`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`POST /api/v2/monitors/demo-webhook`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`POST /api/v2/monitors/batch`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`GET /api/v2/monitors/{id}/runs`

2 accepted parameters.

Parameter	Type	Constraints	Description
`limit`	limit	min 1, max 100, default `25`	Runs per page. Default 25, max 100. A value outside the range is refused, not clamped.
`offset`	integer	min 0, max 100000, default `0`	Rows to skip, for paging back through the seven-day retention window. Plain integer offset — this endpoint has no opaque cursor.

`GET /api/v2/monitors/{id}/runs/{runId}`

Takes no query parameters.

`GET /api/v2/monitors/{id}/runs/{runId}/matches`

2 accepted parameters.

Parameter	Type	Constraints	Description
`limit`	limit	min 1, max 100, default `25`	Matched items per page. Default 25, max 100. A value outside the range is refused, not clamped.
`cursor`	cursor	—	Opaque cursor over the run’s frozen matched-item list. Copy `next_cursor` from the previous response verbatim; omit it for the first page, and stop when it is null. It is not an offset — a plain integer is refused rather than answered with page one.

`GET /api/v2/monitors/{id}/runs/{runId}/matches.csv`

Takes no query parameters.

`POST /api/v2/monitors/{id}/run-now`

Takes no query parameters.

`POST /api/v2/monitors/{id}/test-delivery`

Takes no query parameters.

`GET /api/v2/briefs/{id}`

Takes no query parameters.

`GET /api/v2/briefs`

Takes no query parameters.

`POST /api/v2/briefs`

Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.

`GET /api/v2/bulk/files/{file_id}/url`

Takes no query parameters.

`GET /api/v2/bulk/files`

Takes no query parameters.

`GET /api/v2/china/projects`

Takes no query parameters.

`GET /api/v2/china/projects/summary`

Takes no query parameters.

`GET /api/v2/energy/assets/{tracker}/{gem_id}`

Takes no query parameters.

`GET /api/v2/energy/assets/map`

Takes no query parameters.

`GET /api/v2/energy/assets`

Takes no query parameters.

`GET /api/v2/energy/assets/summary`

Takes no query parameters.

`GET /api/v2/energy/owners/{entity_id}`

Takes no query parameters.

`GET /api/v2/energy/owners`

Takes no query parameters.

`GET /api/v2/entities/{entity_id}/hierarchy`

Takes no query parameters.

`GET /api/v2/entities/{entity_id}`

Takes no query parameters.

`GET /api/v2/entities/{entity_id}/tone`

Takes no query parameters.

`GET /api/v2/entity-tone`

Takes no query parameters.

`GET /api/v2/entity-tone/runs/{run_id}`

Takes no query parameters.

`GET /api/v2/entity-tone/runs`

Takes no query parameters.

`POST /api/v2/entity-tone/runs`

Takes no query parameters.

`GET /api/v2/epoch/{...unknown}`

Takes no query parameters.

`POST /api/v2/epoch/{...unknown}`

Takes no query parameters.

`PUT /api/v2/epoch/{...unknown}`

Takes no query parameters.

`PATCH /api/v2/epoch/{...unknown}`

Takes no query parameters.

`DELETE /api/v2/epoch/{...unknown}`

Takes no query parameters.

`GET /api/v2/epoch/chip-sales`

Takes no query parameters.

`GET /api/v2/epoch/companies`

Takes no query parameters.

`GET /api/v2/epoch/data-centers`

Takes no query parameters.

`GET /api/v2/epoch/hardware`

Takes no query parameters.

`GET /api/v2/epoch/models`

Takes no query parameters.

`GET /api/v2/events/{event_id}`

Takes no query parameters.

`GET /api/v2/events/{event_id}/stories`

Takes no query parameters.

`GET /api/v2/filings/{cik}/facts`

Takes no query parameters.

`GET /api/v2/filings/{cik}/relations`

Takes no query parameters.

`GET /api/v2/filings/{cik}`

Takes no query parameters.

`GET /api/v2/filings/events`

Takes no query parameters.

`GET /api/v2/filings`

Takes no query parameters.

`GET /api/v2/filings/summary`

Takes no query parameters.

`GET /api/v2/gleif/entities/{lei}`

Takes no query parameters.

`GET /api/v2/gleif/entities`

Takes no query parameters.

`GET /api/v2/gleif/isin`

Takes no query parameters.

`GET /api/v2/gleif/relationships`

Takes no query parameters.

`GET /api/v2/gov/awards`

Takes no query parameters.

`GET /api/v2/gov/enforcement`

Takes no query parameters.

`GET /api/v2/gov/fara`

Takes no query parameters.

`GET /api/v2/macro/observations`

Takes no query parameters.

`GET /api/v2/macro/releases`

Takes no query parameters.

`GET /api/v2/macro/series/{series_id}`

Takes no query parameters.

`GET /api/v2/macro/series`

Takes no query parameters.

`GET /api/v2/maritime/activity`

Takes no query parameters.

`GET /api/v2/maritime/carriers/{imo}`

Takes no query parameters.

`GET /api/v2/maritime/chokepoint-watch`

Takes no query parameters.

`GET /api/v2/maritime/density`

Takes no query parameters.

`GET /api/v2/maritime/dwell`

Takes no query parameters.

`GET /api/v2/maritime/gaps`

Takes no query parameters.

`GET /api/v2/maritime/port-pulse`

Takes no query parameters.

`GET /api/v2/maritime/ports`

Takes no query parameters.

`GET /api/v2/maritime/tracks`

Takes no query parameters.

`GET /api/v2/maritime/transits`

Takes no query parameters.

`GET /api/v2/maritime/vessels/{imo}/track`

Takes no query parameters.

`GET /api/v2/maritime/vessels`

Takes no query parameters.

`GET /api/v2/markets`

Takes no query parameters. Takes no query parameters.

`GET /api/v2/stories/{story_id}`

Takes no query parameters.

Identifier parameters

Identifiers are keys with a format, not vocabularies — resolve one with GET /api/v2/search rather than constructing it. Several identifier spaces coexist, and the set an endpoint accepts differs by endpoint. Passing an id from the wrong space generally returns an empty 200 rather than a 400, so read the row for the endpoint you are about to call before you chain it to another one. This table is generated from the published spec and prints each parameter’s own description, unsummarised, so a difference between two endpoints is visible rather than averaged away.

`cik`

On 6 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/filings`	One or more CIK numbers (comma-separated).
`/api/v2/filings/{cik}`	SEC CIK number.
`/api/v2/filings/{cik}/facts`	SEC CIK number.
`/api/v2/filings/{cik}/relations`	SEC CIK number.
`/api/v2/filings/events`	One or more CIK numbers (comma-separated).
`/api/v2/filings/resolve`	SEC CIK, with or without zero padding. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

`entity`

On 15 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/activity`	Selected entity ID from /api/v2/search; returns records linked to that identity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
`/api/v2/energy/assets`	Canonical owner selector — the same `entity` value works across endpoints. Pass a spine entity id (e_…) for an EXACT match against an asset’s owners, operators, or parents, or any name for a case-insensitive fuzzy owner-name match. Preferred over the legacy `owner_search` param.
`/api/v2/energy/assets/map`	Canonical owner selector — the same `entity` value works across endpoints. Pass a spine entity id (e_…) for an EXACT match against an asset’s owners, operators, or parents, or any name for a case-insensitive fuzzy owner-name match. Preferred over the legacy `owner_search` param.
`/api/v2/energy/assets/summary`	Canonical owner selector — the same `entity` value works across endpoints. Pass a spine entity id (e_…) for an EXACT match against an asset’s owners, operators, or parents, or any name for a case-insensitive fuzzy owner-name match. Preferred over the legacy `owner_search` param.
`/api/v2/events`	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
`/api/v2/events/summary`	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
`/api/v2/exposure`	Resolved entity identifier. `entity_id` is an alias. Also accepts: `entity_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.
`/api/v2/facilities`	Owner filter. An `e_` spine id matches the resolved owner exactly; a name falls back to a fuzzy match on owner names. Also accepts: `owner_entity_id`, `owner_search`, `owner`. 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
`/api/v2/filings`	Restrict to one entity’s SEC filings. Takes the SAME entity identifier as the other per-entity surfaces — a spine `e_…` id, a news `wiki:…`/`llm:…` id, or a merged alias of either — resolved through the shared resolver, so the id you used on `/api/v2/events` or `/api/v2/gov/awards` selects the same company here. Resolution maps the entity to its SEC Central Index Key(s); the applied set is echoed as `applied_filters.entity_cik`, and an entity carrying two filer numbers matches BOTH. An entity-scoped read is a primary-key seek, so it is NOT capped at 30 days (it defaults to the last year, like `cik`). A known entity with no SEC filer identity returns an empty result with a `note` — never the unfiltered feed — and an identifier that resolves to no known entity is refused with `400 UNRESOLVED_ENTITY_ID` rather than silently ignored. Combine with `cik` to intersect the two. Also accepts: `entity_id`. Resolve a NAME first with `GET /api/v2/search` or `GET /api/v2/filings/resolve?q=<name>`.
`/api/v2/gov/awards`	A resolved spine entity id (`e_…` / `wiki:…` / `cik:…`). A bare name is rejected with 400 INVALID_ENTITY_ID — resolve it first via GET /api/v2/search. Returns that entity’s federal awards.
`/api/v2/gov/fara`	A resolved spine entity id (`e_…`). Matches the registrant OR the foreign principal side of the link.
`/api/v2/lists/entries`	Only entries resolved to this entity — an `e_` spine id or a `wiki:` news id, collapsed through the arbiter. `entity_id` is an alias. An id the registry has never heard of answers `400 UNRESOLVED_ENTITY_ID` rather than an empty list. Also accepts: `entity_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.
`/api/v2/situations`	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.
`/api/v2/stories`	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
`/api/v2/stories/summary`	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

`entity_id`

On 8 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/energy/owners`	Exact GEM ownership entity ID.
`/api/v2/energy/owners/{entity_id}`	GEM ownership entity ID.
`/api/v2/entities/{entity_id}`	Entity ID returned by Search Entities or an entity_refs array. Wikipedia URLs are valid IDs and must be URL-encoded.
`/api/v2/entities/{entity_id}/dossier`	The entity id.
`/api/v2/entities/{entity_id}/hierarchy`	A name, an `e_` spine id, a `wiki:` news id, a wikipedia_url, or a bare 20-character LEI.
`/api/v2/entities/{entity_id}/offices`	The entity id.
`/api/v2/entities/{entity_id}/tone`	Canonical entity id or wikipedia_url.
`/api/v2/entity-tone`	Canonical entity id / wikipedia_url.

`entity_search`

On 3 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/entity-tone`	Resolve by name instead of id.
`/api/v2/entity-tone/runs`	Entity to score.
`/api/v2/exposure`	Fuzzy entity resolver query. `q` and `counterparty` are aliases. Also accepts: `q`, `counterparty`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

`facility_id`

On 3 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/facilities/{facility_id}`	The facility id.
`/api/v2/facilities/{facility_id}/context`	The facility id.
`/api/v2/facilities/{facility_id}/units`	The facility id.

`gem_id`

On 2 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/energy/assets/{tracker}/{gem_id}`	GEM asset ID returned by Search Energy Assets.
`/api/v2/exposure`	GEM asset 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.

`imo`

On 2 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/maritime/carriers/{imo}`	IMO number of the vessel (e.g. 9006681).
`/api/v2/maritime/vessels/{imo}/track`	IMO number of the vessel (e.g. 9006681).

`isin`

On 1 endpoint.

Endpoint	What this endpoint says it accepts
`/api/v2/gleif/isin`	ISIN to resolve back to its LEI.

`lei`

On 4 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/gleif/entities`	One or more LEIs, comma-separated (max 100). Each must pass the ISO 17442 check digit.
`/api/v2/gleif/entities/{lei}`	A 20-character LEI passing the ISO 17442 check digit.
`/api/v2/gleif/isin`	LEI to resolve to ISINs.
`/api/v2/gleif/relationships`	Match relationships where this LEI is either endpoint. Must pass the ISO 17442 check digit.

`near_gem_id`

On 6 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/maritime/activity`	GEM energy-asset gem_id center — traffic within radius_km of that LNG terminal / platform (default 25 km). The cross-source ‘traffic near energy infrastructure’ join.
`/api/v2/maritime/density`	GEM energy-asset gem_id center — concentration of traffic within radius_km of that asset (default 25 km). One of bbox / near / near_gem_id is required.
`/api/v2/maritime/port-pulse`	GEM energy-asset gem_id — scope to ports within radius_km of that asset (cross-source join).
`/api/v2/maritime/ports`	GEM energy-asset gem_id — returns ports within radius_km of that LNG terminal / platform / port (cross-source join).
`/api/v2/maritime/tracks`	GEM energy-asset gem_id center — points within radius_km of that asset (default 25 km). Rows include distance_km. One of chokepoint / bbox / near / near_gem_id is required.
`/api/v2/maritime/vessels`	GEM energy-asset gem_id (resolved via gem.assets_view) — returns vessels within radius_km of that LNG terminal / platform / port. The cross-source ‘vessels near energy infrastructure’ join.

`owner_entity_id`

On 3 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/energy/assets`	GEM Entity ID. Returns assets where the entity appears in owners, operators, or parents.
`/api/v2/energy/assets/map`	GEM Entity ID. Returns assets where the entity appears in owners, operators, or parents.
`/api/v2/energy/assets/summary`	GEM Entity ID. Returns assets where the entity appears in owners, operators, or parents.

`owner_search`

On 3 endpoints.

Endpoint	What this endpoint says it accepts
`/api/v2/energy/assets`	Legacy — prefer the canonical `entity` param (still fully supported). Case-insensitive substring match against the raw owner string.
`/api/v2/energy/assets/map`	Legacy — prefer the canonical `entity` param (still fully supported). Case-insensitive substring match against the raw owner string.
`/api/v2/energy/assets/summary`	Legacy — prefer the canonical `entity` param (still fully supported). Case-insensitive substring match against the raw owner string.

`ticker`

On 1 endpoint.

Endpoint	What this endpoint says it accepts
`/api/v2/filings/resolve`	Exact ticker symbol. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

`uei`

On 1 endpoint.

Endpoint	What this endpoint says it accepts
`/api/v2/gov/awards`	A SAM.gov Unique Entity Identifier (12-char). Case-insensitive.

Unknown parameters never become silent filters

Descriptor-backed endpoints reject an undeclared query parameter with 400 UNKNOWN_PARAM; details.did_you_mean and details.accepted_params make typos actionable. Endpoints still being migrated to that contract may return a successful response and place the parameter under applied_filters.ignored. On any successful response, treat a non-empty ignored object as a client error: those parameters did not affect the rows.

​Shared parameters

​Aliases

​Deliberately rejected parameters

​Deprecated parameters

​Per-endpoint parameters

​GET /api/v2/activity

​GET /api/v2/countries

​GET /api/v2/countries/{iso3}

​GET /api/v2/events

​GET /api/v2/stories

​GET /api/v2/events/summary

​GET /api/v2/stories/summary

​GET /api/v2/facilities

​GET /api/v2/facilities/{facility_id}

​GET /api/v2/facilities/{facility_id}/units

​GET /api/v2/facilities/{facility_id}/context

​GET /api/v2/intelligence/gpr

​GET /api/v2/intelligence/posture

​GET /api/v2/intelligence/coverage

​GET /api/v2/filings/resolve

​GET /api/v2/screening/match

​GET /api/v2/exposure

​GET /api/v2/share-of-voice

​GET /api/v2/stories/{story_id}/articles

​GET /api/v2/lists

​GET /api/v2/lists/entries

​GET /api/v2/lists/changes

​GET /api/v2/meta/enums

​GET /api/v2/meta/endpoints

​GET /api/v2/meta/query-units

​GET /api/v2/search

​GET /api/v2/situations

​GET /api/v2/situations/{story_id}

​GET /api/v2/situations/{story_id}/entities

​GET /api/v2/situations/{story_id}/stories

​GET /api/v2/situations/{story_id}/events

​GET /api/v2/situations/{story_id}/connections

​POST /api/v2/situations

​GET /api/v2/entities

​GET /api/v2/entities/{entity_id}/dossier

​GET /api/v2/offices

​GET /api/v2/offices/{office_id}

​GET /api/v2/offices/{office_id}/holders

​GET /api/v2/entities/{entity_id}/offices

​GET /api/v2/geo/admin1

​GET /api/v2/monitors

​POST /api/v2/monitors

​GET /api/v2/monitors/{id}

​PATCH /api/v2/monitors/{id}

​DELETE /api/v2/monitors/{id}

​POST /api/v2/monitors/preview

​POST /api/v2/monitors/demo-webhook

​POST /api/v2/monitors/batch

​GET /api/v2/monitors/{id}/runs

​GET /api/v2/monitors/{id}/runs/{runId}

​GET /api/v2/monitors/{id}/runs/{runId}/matches

​GET /api/v2/monitors/{id}/runs/{runId}/matches.csv

​POST /api/v2/monitors/{id}/run-now

​POST /api/v2/monitors/{id}/test-delivery

​GET /api/v2/briefs/{id}

​GET /api/v2/briefs

​POST /api/v2/briefs

​GET /api/v2/bulk/files/{file_id}/url

​GET /api/v2/bulk/files

​GET /api/v2/china/projects

​GET /api/v2/china/projects/summary

​GET /api/v2/energy/assets/{tracker}/{gem_id}

​GET /api/v2/energy/assets/map

​GET /api/v2/energy/assets

​GET /api/v2/energy/assets/summary

​GET /api/v2/energy/owners/{entity_id}

​GET /api/v2/energy/owners

​GET /api/v2/entities/{entity_id}/hierarchy

​GET /api/v2/entities/{entity_id}

​GET /api/v2/entities/{entity_id}/tone

​GET /api/v2/entity-tone

​GET /api/v2/entity-tone/runs/{run_id}

​GET /api/v2/entity-tone/runs

​POST /api/v2/entity-tone/runs

​GET /api/v2/epoch/{...unknown}

Shared parameters

Aliases

Deliberately rejected parameters

Deprecated parameters

Per-endpoint parameters

`GET /api/v2/activity`

`GET /api/v2/countries`

`GET /api/v2/countries/{iso3}`

`GET /api/v2/events`

`GET /api/v2/stories`

`GET /api/v2/events/summary`

`GET /api/v2/stories/summary`

`GET /api/v2/facilities`

`GET /api/v2/facilities/{facility_id}`

`GET /api/v2/facilities/{facility_id}/units`

`GET /api/v2/facilities/{facility_id}/context`

`GET /api/v2/intelligence/gpr`

`GET /api/v2/intelligence/posture`

`GET /api/v2/intelligence/coverage`

`GET /api/v2/filings/resolve`

`GET /api/v2/screening/match`

`GET /api/v2/exposure`

`GET /api/v2/share-of-voice`

`GET /api/v2/stories/{story_id}/articles`

`GET /api/v2/lists`

`GET /api/v2/lists/entries`

`GET /api/v2/lists/changes`

`GET /api/v2/meta/enums`

`GET /api/v2/meta/endpoints`

`GET /api/v2/meta/query-units`

`GET /api/v2/search`

`GET /api/v2/situations`

`GET /api/v2/situations/{story_id}`

`GET /api/v2/situations/{story_id}/entities`

`GET /api/v2/situations/{story_id}/stories`

`GET /api/v2/situations/{story_id}/events`

`GET /api/v2/situations/{story_id}/connections`

`POST /api/v2/situations`

`GET /api/v2/entities`

`GET /api/v2/entities/{entity_id}/dossier`

`GET /api/v2/offices`

`GET /api/v2/offices/{office_id}`

`GET /api/v2/offices/{office_id}/holders`

`GET /api/v2/entities/{entity_id}/offices`

`GET /api/v2/geo/admin1`

`GET /api/v2/monitors`

`POST /api/v2/monitors`

`GET /api/v2/monitors/{id}`

`PATCH /api/v2/monitors/{id}`

`DELETE /api/v2/monitors/{id}`

`POST /api/v2/monitors/preview`

`POST /api/v2/monitors/demo-webhook`

`POST /api/v2/monitors/batch`

`GET /api/v2/monitors/{id}/runs`

`GET /api/v2/monitors/{id}/runs/{runId}`

`GET /api/v2/monitors/{id}/runs/{runId}/matches`

`GET /api/v2/monitors/{id}/runs/{runId}/matches.csv`

`POST /api/v2/monitors/{id}/run-now`

`POST /api/v2/monitors/{id}/test-delivery`

`GET /api/v2/briefs/{id}`

`GET /api/v2/briefs`

`POST /api/v2/briefs`

`GET /api/v2/bulk/files/{file_id}/url`

`GET /api/v2/bulk/files`

`GET /api/v2/china/projects`

`GET /api/v2/china/projects/summary`

`GET /api/v2/energy/assets/{tracker}/{gem_id}`

`GET /api/v2/energy/assets/map`

`GET /api/v2/energy/assets`

`GET /api/v2/energy/assets/summary`

`GET /api/v2/energy/owners/{entity_id}`

`GET /api/v2/energy/owners`

`GET /api/v2/entities/{entity_id}/hierarchy`

`GET /api/v2/entities/{entity_id}`

`GET /api/v2/entities/{entity_id}/tone`

`GET /api/v2/entity-tone`

`GET /api/v2/entity-tone/runs/{run_id}`

`GET /api/v2/entity-tone/runs`

`POST /api/v2/entity-tone/runs`

`GET /api/v2/epoch/{...unknown}`