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 inapplied_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 return400 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 withGET /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 |
/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 |
/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/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 |
/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 |
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 with400 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.