> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Parameter reference > Shared and identifier parameters across the v2 API, plus the full parameter list for the contract-governed endpoints. 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](/api-reference); the [identifier section](#identifier-parameters) below is derived from the whole published surface. ## Shared parameters 57 parameters appear on more than one endpoint and mean the same thing on each. Learn these once. | Parameter | Type | Constraints | On | | --------------------------- | -------------------------- | ---------------------------------- | ------------ | | `actor_country` | enum `country` | case-insensitive | 2 endpoints | | `admin1` | csv | — | 4 endpoints | | `article_count_max` | number | min 0 | 2 endpoints | | `article_count_min` | number | min 0 | 2 endpoints | | `as_of` | date | — | 2 endpoints | | `bbox` | bbox | — | 5 endpoints | | `category` | enum `event_category` | — | 5 endpoints | | `civilian_targeting` | boolean | — | 4 endpoints | | `collapse_duplicates` | boolean | default `false` | 2 endpoints | | `confidence_max` | number | min 0, max 1 | 2 endpoints | | `confidence_min` | number | min 0, max 1 | 2 endpoints | | `continent` | enum `continent` | — | 7 endpoints | | `country` | csv | case-insensitive | 7 endpoints | | `country_match` | enum `country_match` | default `location_or_actor_origin` | 4 endpoints | | `cursor` | cursor | — | 7 endpoints | | `date` | date | — | 7 endpoints | | `date_end` | date | — | 6 endpoints | | `date_start` | date | — | 6 endpoints | | `days` | duration | default `7` | 7 endpoints | | `end_date` | date | — | 2 endpoints | | `entity` | enum `entity_handle` | — | 6 endpoints | | `entity_match` | enum `entity_match` | default `material` | 4 endpoints | | `event_category` | enum `event_category` | — | 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` | default `date` | 3 endpoints | | `has_events` | boolean | — | 2 endpoints | | `has_fatalities` | boolean | — | 4 endpoints | | `incident_resolution` | enum `incident_resolution` | — | 2 endpoints | | `include_images` | boolean | default `false` | 3 endpoints | | `languages` | csv | — | 5 endpoints | | `limit` | limit | min 1, max 100, default `25` | 12 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 | — | 2 endpoints | | `observed_end` | date | — | 4 endpoints | | `observed_start` | date | — | 4 endpoints | | `offset` | integer | min 0 | 4 endpoints | | `propagation_potential_max` | number | min 0, max 1 | 2 endpoints | | `propagation_potential_min` | number | min 0, max 1 | 2 endpoints | | `q` | string | — | 3 endpoints | | `region` | enum `region` | — | 7 endpoints | | `search` | string | — | 2 endpoints | | `significance_max` | number | min 0, max 1 | 2 endpoints | | `significance_min` | number | min 0, max 1 | 2 endpoints | | `sort` | enum `sort` | default `significance` | 4 endpoints | | `source_actor_country` | enum `country` | case-insensitive | 2 endpoints | | `start_date` | date | — | 2 endpoints | | `story_category` | enum `story_category` | — | 2 endpoints | | `subcategory` | csv | — | 4 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 | ## 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` | | `category` | `categories` | | `component` | `decompose` | | `country` | `country_iso3` | | `cursor` | `offset` | | `date_end` | `end_date` | | `date_start` | `start_date` | | `days` | `window` | | `end_date` | `date_end` | | `entities` | `entity_id`, `entity` | | `entity` | `entity_id`, `entities` | | `entity_query` | `entity_search`, `entity_terms`, `numerator` | | `entity_search` | `q`, `counterparty` | | `event_category` | `event_categories` | | `geo` | `id` | | `incident_resolution` | `incident_resolutions` | | `include_images` | `include_entity_images` | | `language` | `languages` | | `languages` | `language` | | `list` | `source` | | `min_match_confidence` | `threshold` | | `observed_end` | `observedEnd` | | `observed_start` | `observedStart` | | `publisher_country_iso3` | `publisher_country` | | `q` | `search` | | `search` | `q`, `query`, `keyword`, `name` | | `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/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/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` | | `/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` | ## 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. | 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` | ## Per-endpoint parameters ### `/api/v2/events` 51 accepted parameters. | Parameter | Type | Constraints | Description | | --------------------------- | -------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_start` | date | — | Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. | | `date_end` | date | — | Inclusive end of the window (YYYY-MM-DD). | | `days` | duration | default `7` | Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. | | `date` | date | — | Single-day anchor — equivalent to date\_start = date\_end = this value. | | `observed_start` | date | — | Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. | | `observed_end` | date | — | Upper bound on the coded-at window. | | `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. | | `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. | | `admin1` | csv | — | Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. | | `bbox` | bbox | — | Bounding box `lat_min,lon_min,lat_max,lon_max`. | | `near` | point | — | Point proximity `lat,lon`, combined with `radius_km`. Applied as the enclosing bounding box, not a true distance filter — results are a deliberate superset. | | `lat` | number | — | Point proximity component (`lat`), an alternative spelling of `near`. | | `lon` | number | — | Point proximity component (`lon`), an alternative spelling of `near`. | | `lng` | number | — | Point proximity component (`lng`), an alternative spelling of `near`. | | `radius_km` | number | — | Radius in km for point proximity. Default 100, capped 2000. | | `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` | enum `entity_handle` | — | Restrict to one 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. | | `entity_match` | enum `entity_match` | default `material` | Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. | | `category` | enum `event_category` | — | 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). | | `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). | | `search` | string | — | Semantic search — 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. Aliases `q`, `query`, `keyword`. | | `sort` | enum `sort` | default `significance` | Ranking. A bare `search` with no explicit sort ranks by relevance instead. | | `incident_resolution` | enum `incident_resolution` | — | Restrict to events by whether they were checked for duplication. Comma-separated. Adjudication is deliberately partial, so `llm,self` is how you get the subset where `incident.uid` is a trustworthy grouping key; omitting the filter returns everything, most of which is `unadjudicated`. | | `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. | | `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 story images to each card. Off by default — images cost an extra lookup, so pass `true` to opt in. | | `collapse_duplicates` | boolean | default `false` | Fold Events adjudicated as the same real-world incident. Off by default for compatibility; Alerts enable it by default. Unadjudicated Events remain distinct. | ### `/api/v2/stories` 31 accepted parameters. | Parameter | Type | Constraints | Description | | --------------------- | --------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_start` | date | — | Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. | | `date_end` | date | — | Inclusive end of the window (YYYY-MM-DD). | | `days` | duration | default `7` | Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. | | `date` | date | — | Single-day anchor — equivalent to date\_start = date\_end = this value. | | `observed_start` | date | — | Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. | | `observed_end` | date | — | Upper bound on the coded-at window. | | `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. | | `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. | | `admin1` | csv | — | Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. | | `bbox` | bbox | — | Bounding box `lat_min,lon_min,lat_max,lon_max`. | | `entity` | enum `entity_handle` | — | Restrict to one 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. | | `entity_match` | enum `entity_match` | default `material` | Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. | | `category` | enum `event_category` | — | 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. | | `search` | string | — | Semantic search — 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. Aliases `q`, `query`, `keyword`. | | `story_category` | enum `story_category` | — | Story-level category. | | `event_category` | enum `event_category` | — | Legacy alias for `category` on Stories. Merges with `category` into one union filter. | | `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 story images. Off by default — images cost an extra lookup, so pass `true` to opt in. | | `sort` | enum `sort` | default `significance` | Ranking. | | `related` | boolean | — | Attach related Stories (schema 130). | | `collapse_duplicates` | boolean | default `true` | Collapse near-duplicate Stories. On by default for compatibility; pass `false` for the stable raw Story-id walk. | ### `/api/v2/events/summary` 41 accepted parameters. | Parameter | Type | Constraints | Description | | --------------------------- | -------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_start` | date | — | Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. | | `date_end` | date | — | Inclusive end of the window (YYYY-MM-DD). | | `days` | duration | default `7` | Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. | | `date` | date | — | Single-day anchor — equivalent to date\_start = date\_end = this value. | | `observed_start` | date | — | Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. | | `observed_end` | date | — | Upper bound on the coded-at window. | | `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. | | `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. | | `admin1` | csv | — | Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. | | `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` | enum `entity_handle` | — | Restrict to one 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. | | `entity_match` | enum `entity_match` | default `material` | Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. | | `category` | enum `event_category` | — | 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). | | `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). | | `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. | | `incident_resolution` | enum `incident_resolution` | — | Restrict to events by whether they were checked for duplication. Comma-separated. Adjudication is deliberately partial, so `llm,self` is how you get the subset where `incident.uid` is a trustworthy grouping key; omitting the filter returns everything, most of which is `unadjudicated`. | | `languages` | csv | — | Coverage-language filter (ISO 639-1/2) on the underlying articles. | ### `/api/v2/stories/summary` 26 accepted parameters. | Parameter | Type | Constraints | Description | | -------------------- | --------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_start` | date | — | Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. | | `date_end` | date | — | Inclusive end of the window (YYYY-MM-DD). | | `days` | duration | default `7` | Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. | | `date` | date | — | Single-day anchor — equivalent to date\_start = date\_end = this value. | | `observed_start` | date | — | Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. | | `observed_end` | date | — | Upper bound on the coded-at window. | | `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. 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`. 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. | | `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. | | `admin1` | csv | — | Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. | | `bbox` | bbox | — | Bounding box `lat_min,lon_min,lat_max,lon_max`. | | `entity` | enum `entity_handle` | — | Restrict to one 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. | | `entity_match` | enum `entity_match` | default `material` | Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. | | `category` | enum `event_category` | — | 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. | | `story_category` | enum `story_category` | — | Story-level topic. Distinct from the EVENT taxonomy that `category` filters. | | `event_category` | enum `event_category` | — | Filter Stories by the EVENT taxonomy of the events linked to them. | | `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. | ### `/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`. | ### `/api/v2/facilities/{facility_id}` Takes no parameters. ### `/api/v2/facilities/{facility_id}/units` Takes no parameters. ### `/api/v2/facilities/{facility_id}/context` 5 accepted parameters. | Parameter | Type | Constraints | Description | | ------------ | ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `days` | duration | default `7` | 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. | ### `/api/v2/intelligence/gpr` 15 accepted parameters. | Parameter | Type | Constraints | Description | | -------------- | ----------------------------- | ------------------------------ | ------------------------------------------------------------------------ | | `construction` | enum `atlas_gpr_construction` | default `own_coverage` | Index construction. | | `variant` | enum `atlas_gpr_variant` | default `events` | GPR lens. `lens` is the legacy alias. | | `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 | — | Trailing display window in days, 1–370. | | `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 1000, default `100` | Maximum observations returned. | | `cursor` | cursor | — | Pagination cursor. | | `offset` | integer | min 0 | Legacy numeric pagination offset. | ### `/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. | ### `/api/v2/screening/match` 6 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. | ### `/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. | ### `/api/v2/share-of-voice` 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. | | `region` | string | — | Region denominator. | | `continent` | string | — | Continent denominator. | | `languages` | csv | — | Language-code denominator. | | `source_set` | string | — | Named source-universe denominator. | | `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. | ### `/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. | ### `/api/v2/meta/enums` Takes no parameters. ### `/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`. | ### `/api/v2/meta/query-units` Takes no parameters. ### `/api/v2/briefs/{id}` Takes no parameters. ### `/api/v2/briefs` Takes no parameters. ### `/api/v2/briefs` Takes no parameters. ### `/api/v2/bulk/files/{file_id}/url` Takes no parameters. ### `/api/v2/bulk/files` Takes no parameters. ### `/api/v2/china/projects` Takes no parameters. ### `/api/v2/china/projects/summary` Takes no parameters. ### `/api/v2/energy/assets/{tracker}/{gem_id}` Takes no parameters. ### `/api/v2/energy/assets/map` Takes no parameters. ### `/api/v2/energy/assets` Takes no parameters. ### `/api/v2/energy/assets/summary` Takes no parameters. ### `/api/v2/energy/owners/{entity_id}` Takes no parameters. ### `/api/v2/energy/owners` Takes no parameters. ### `/api/v2/entities/{entity_id}/dossier` Takes no parameters. ### `/api/v2/entities/{entity_id}/hierarchy` Takes no parameters. ### `/api/v2/entities/{entity_id}` Takes no parameters. ### `/api/v2/entities/{entity_id}/tone` Takes no parameters. ### `/api/v2/entities` Takes no parameters. ### `/api/v2/entity-tone` Takes no parameters. ### `/api/v2/entity-tone/runs/{run_id}` Takes no parameters. ### `/api/v2/entity-tone/runs` Takes no parameters. ### `/api/v2/entity-tone/runs` Takes no parameters. ### `/api/v2/epoch/{...unknown}` Takes no parameters. ### `/api/v2/epoch/{...unknown}` Takes no parameters. ### `/api/v2/epoch/{...unknown}` Takes no parameters. ### `/api/v2/epoch/{...unknown}` Takes no parameters. ### `/api/v2/epoch/{...unknown}` Takes no parameters. ### `/api/v2/epoch/chip-sales` Takes no parameters. ### `/api/v2/epoch/companies` Takes no parameters. ### `/api/v2/epoch/data-centers` Takes no parameters. ### `/api/v2/epoch/hardware` Takes no parameters. ### `/api/v2/epoch/models` Takes no parameters. ### `/api/v2/events/{event_id}` Takes no parameters. ### `/api/v2/events/{event_id}/stories` Takes no parameters. ### `/api/v2/filings/{cik}/facts` Takes no parameters. ### `/api/v2/filings/{cik}/relations` Takes no parameters. ### `/api/v2/filings/{cik}` Takes no parameters. ### `/api/v2/filings/events` Takes no parameters. ### `/api/v2/filings` Takes no parameters. ### `/api/v2/filings/summary` Takes no parameters. ### `/api/v2/geo/admin1` Takes no parameters. ### `/api/v2/gleif/entities/{lei}` Takes no parameters. ### `/api/v2/gleif/entities` Takes no parameters. ### `/api/v2/gleif/isin` Takes no parameters. ### `/api/v2/gleif/relationships` Takes no parameters. ### `/api/v2/gov/awards` Takes no parameters. ### `/api/v2/gov/enforcement` Takes no parameters. ### `/api/v2/gov/fara` Takes no parameters. ### `/api/v2/intelligence/coverage` Takes no parameters. ### `/api/v2/intelligence/posture` Takes no parameters. ### `/api/v2/lists/changes` Takes no parameters. ### `/api/v2/lists/entries` Takes no parameters. ### `/api/v2/lists` Takes no parameters. ### `/api/v2/macro/observations` Takes no parameters. ### `/api/v2/macro/releases` Takes no parameters. ### `/api/v2/macro/series/{series_id}` Takes no parameters. ### `/api/v2/macro/series` Takes no parameters. ### `/api/v2/maritime/activity` Takes no parameters. ### `/api/v2/maritime/carriers/{imo}` Takes no parameters. ### `/api/v2/maritime/chokepoint-watch` Takes no parameters. ### `/api/v2/maritime/density` Takes no parameters. ### `/api/v2/maritime/dwell` Takes no parameters. ### `/api/v2/maritime/gaps` Takes no parameters. ### `/api/v2/maritime/port-pulse` Takes no parameters. ### `/api/v2/maritime/ports` Takes no parameters. ### `/api/v2/maritime/tracks` Takes no parameters. ### `/api/v2/maritime/transits` Takes no parameters. ### `/api/v2/maritime/vessels/{imo}/track` Takes no parameters. ### `/api/v2/maritime/vessels` Takes no parameters. ### `/api/v2/markets` Takes no parameters. ### `/api/v2/search` Takes no parameters. ### `/api/v2/social` Takes no parameters. ### `/api/v2/stories/{story_id}` Takes no 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 11 endpoints. | Endpoint | What this endpoint says it accepts | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/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 one 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. 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](https://docs.gdeltcloud.com/reference/enums#entity_handle) | | `/api/v2/events/summary` | Restrict to one 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. 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](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](https://docs.gdeltcloud.com/reference/enums#entity_handle) | | `/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/stories` | Restrict to one 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. 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](https://docs.gdeltcloud.com/reference/enums#entity_handle) | | `/api/v2/stories/summary` | Restrict to one 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. 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](https://docs.gdeltcloud.com/reference/enums#entity_handle) | ### `entity_id` On 7 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}/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}/tone` | Canonical entity id or wikipedia\_url. | | `/api/v2/entity-tone` | Canonical entity id / wikipedia\_url. | | `/api/v2/lists/entries` | Entries resolved to this entity\_id. | ### `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.