Shared parameters
81 parameter names appear on more than one endpoint. When bounds or defaults differ, use the per-endpoint tables below.| Parameter | Type | Constraints | On |
|---|---|---|---|
actor_country | enum country | case-insensitive | 2 endpoints |
admin1 | csv | — | 4 endpoints |
article_count_max | number | Varies by endpoint; see below | 2 endpoints |
article_count_min | number | Varies by endpoint; see below | 2 endpoints |
as_of | date | — | 14 endpoints |
basis | enum country_basis | default publication | 2 endpoints |
bbox | bbox | — | 5 endpoints |
category | enum event_category | Varies by endpoint; see below | 8 endpoints |
civilian_targeting | boolean | — | 5 endpoints |
commodity | enum resource_commodity | Varies by endpoint; see below | 4 endpoints |
confidence_max | number | min 0, max 1 | 2 endpoints |
confidence_min | number | min 0, max 1 | 2 endpoints |
continent | enum continent | Varies by endpoint; see below | 14 endpoints |
country | string | Varies by endpoint; see below | 18 endpoints |
country_match | enum country_match | Varies by endpoint; see below | 6 endpoints |
cursor | cursor | — | 18 endpoints |
date | date | — | 3 endpoints |
date_end | date | — | 21 endpoints |
date_start | date | — | 21 endpoints |
days | duration | Varies by endpoint; see below | 12 endpoints |
edition_id | string | — | 6 endpoints |
entity | string | — | 11 endpoints |
entity_family | enum entity_family | default expand | 4 endpoints |
geo | string | — | 2 endpoints |
geo_precision_max | number | min 1, max 3 | 2 endpoints |
geo_precision_min | number | min 1, max 3 | 2 endpoints |
goldstein_scale_max | number | min -10, max 10 | 2 endpoints |
goldstein_scale_min | number | min -10, max 10 | 2 endpoints |
group_by | enum event_group_by | Varies by endpoint; see below | 4 endpoints |
has_events | boolean | — | 2 endpoints |
has_fatalities | boolean | — | 5 endpoints |
hour | integer | min 0, max 23 | 3 endpoints |
include | enum country_include | — | 3 endpoints |
include_entity_images | boolean | default true | 2 endpoints |
include_images | boolean | Varies by endpoint; see below | 5 endpoints |
languages | csv | — | 7 endpoints |
level | enum atlas_level | Varies by endpoint; see below | 3 endpoints |
limit | limit | Varies by endpoint; see below | 35 endpoints |
list | enum exposure_list | Varies by endpoint; see below | 3 endpoints |
magnitude_max | number | min 0, max 10 | 2 endpoints |
magnitude_min | number | min 0, max 10 | 2 endpoints |
market_sensitivity_max | number | min 0, max 1 | 2 endpoints |
market_sensitivity_min | number | min 0, max 1 | 2 endpoints |
near | point | — | 3 endpoints |
nearby_radius_km | number | Varies by endpoint; see below | 3 endpoints |
observed_end | date_or_instant | — | 4 endpoints |
observed_start | date_or_instant | — | 4 endpoints |
office | enum office_id | — | 4 endpoints |
office_as_of | date | — | 4 endpoints |
offset | integer | Varies by endpoint; see below | 12 endpoints |
propagation_potential_max | number | min 0, max 1 | 2 endpoints |
propagation_potential_min | number | min 0, max 1 | 2 endpoints |
q | string | Varies by endpoint; see below | 8 endpoints |
radius_km | number | Varies by endpoint; see below | 3 endpoints |
record_ids | string | — | 2 endpoints |
region | enum region | Varies by endpoint; see below | 14 endpoints |
related_scope | enum related_scope | default direct | 6 endpoints |
resolved_only | boolean | default false | 2 endpoints |
scope | enum resource_statistic_scope | Varies by endpoint; see below | 3 endpoints |
scope_version | string | — | 4 endpoints |
search | string | — | 5 endpoints |
significance_max | number | min 0, max 1 | 2 endpoints |
significance_min | number | min 0, max 1 | 2 endpoints |
sort | enum country_directory_sort | Varies by endpoint; see below | 10 endpoints |
source | enum resource_statistic_source | Varies by endpoint; see below | 4 endpoints |
source_actor_country | enum country | case-insensitive | 2 endpoints |
status | enum facility_status | case-insensitive | 3 endpoints |
story_category | enum story_category | — | 2 endpoints |
story_search | string | — | 3 endpoints |
subcategory | csv | — | 5 endpoints |
systemic_importance_max | number | min 0, max 1 | 2 endpoints |
systemic_importance_min | number | min 0, max 1 | 2 endpoints |
target_actor_country | enum country | case-insensitive | 2 endpoints |
target_ids | csv | — | 6 endpoints |
target_type | enum target_type | — | 6 endpoints |
time_basis | enum activity-time-basis | default published | 3 endpoints |
type | enum facility_type | — | 3 endpoints |
view | enum monitor-run-view | default full | 2 endpoints |
weighting | enum atlas_weighting | default attention | 2 endpoints |
window | duration | Varies by endpoint; see below | 3 endpoints |
year | integer | min 1900, max 2100 | 2 endpoints |
Older names
The API still accepts older spellings of some parameters. Older parameter names lists each one with the name to send instead.Per-endpoint parameters
GET /api/v2/saved-queries
Takes no query parameters.
POST /api/v2/saved-queries
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
GET /api/v2/saved-queries/{id}
Takes no query parameters.
PATCH /api/v2/saved-queries/{id}
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
DELETE /api/v2/saved-queries/{id}
Takes no query parameters.
GET /api/v2/facility-examples/{slug}
Takes no query parameters.
GET /api/v2/resources/statistics
15 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 200, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
source | enum resource_statistic_source | case-insensitive | Contributing publisher/source identifier from the returned records or source catalog. |
country | string | — | Country name, ISO-2 or ISO-3; comma-separated inputs are allowed. Geography filters select country-scoped rows only. |
country_iso3 | string | — | Country name or ISO country code for country-scoped source observations; comma-separated countries are combined as alternatives. |
region | enum region | case-insensitive | Geographic region whose member countries define the scope. |
continent | enum continent | case-insensitive | Continent whose member countries define the geographic scope. |
commodity | enum resource_commodity | case-insensitive | Exact normalized commodity key; observed suggestions are open and not an allowlist. Aggregate rare-earth oxides differ from individual elements. |
statistic | enum resource_statistic | case-insensitive | Exact source statistic name; observed suggestions are open and not an allowlist. |
statistic_detail | string | — | Native source qualifier for a statistic; use the returned statistic_detail to distinguish observations with the same statistic name. |
material_type | string | — | Source-reported kind of material represented by the statistic; copy the returned material_type when narrowing observations. |
material_form | string | — | Source-reported form of the material, such as an ore or refined product; copy the returned material_form. |
scope | enum resource_statistic_scope | case-insensitive | country, aggregate or unresolved source scope. |
year | integer | min 1900, max 2100 | Source reference year. |
include_summary | boolean | default false | Include count-only aggregates for the full filtered result before pagination. Values are never summed across sources, years or units. |
GET /api/v2/facilities/{facility_id}/relationships
4 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 200, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
claim_status | enum facility_claim_status | — | Filter assertion status. Default includes reported, probable and verified; unresolved can be requested explicitly. Claim confidence is independent of identity resolution. |
relation_type | string | — | Exact physical relation type. |
GET /api/v2/facilities/{facility_id}/observations
5 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 200, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
source | string | — | Contributing publisher/source identifier from the returned records or source catalog. |
commodity | string | — | Exact normalized commodity key. |
year | integer | min 1900, max 2100 | Source reference year. |
GET /api/v2/activity
15 accepted parameters — 7 core, 8 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time. |
date_end | date | — | Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day. |
country | enum country | — | Known country attribution. Evidence distinguishes location, actor origin, reporting and source association. |
kind | enum activity-kind | — | Published record type to include in activity evidence. |
entity | string | — | Selected entity ID from /api/v2/search; returns records linked to that identity. |
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; pagination describes how to continue. |
cursor | string | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
time_basis | enum activity-time-basis | default published. With time_basis=published: cannot be combined with recorded_start or recorded_end. A recorded interval is always read on the recorded clock. | Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged. |
hour | integer | min 0, max 23. Requires date_start and date_end to be equal when both are sent. An hour selects one UTC date. | UTC hour selecting a publication bucket on one UTC date. Rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day. |
recorded_start | instant | Requires recorded_end. Cannot be combined with date_start, date_end or hour. A recorded interval replaces the reporting window. | Inclusive start of API publication time, as an ISO UTC timestamp. Includes late arrivals without changing when the event happened. |
recorded_end | instant | Requires recorded_start. Cannot be combined with date_start, date_end or hour. A recorded interval replaces the reporting window. | Exclusive end of API publication time, as an ISO UTC timestamp. Includes late arrivals without changing when the event happened. |
target_type | enum target_type | Requires target_ids. | Typed selected root for a shared connected scope: entity or facility. |
target_ids | csv | Requires target_type. Cannot be combined with entity. Use either entity or a typed target scope. | Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. |
related_scope | enum related_scope | default direct. Requires target_type and target_ids. | direct matches the selected targets only. connected also matches, for an entity, the companies it owns or consolidates: subsidiaries its SEC Exhibit 21 lists and its GLEIF consolidated children, direct or naming it as ultimate parent, down five levels and up to 250 companies per target. Only companies that are themselves registry entities are added, and an entity target expands only from its e_… registry id. For a facility, connected adds its identified owners and their parent companies. applied_filters.relationship_paths lists each added company and the relationship that added it; applied_filters.target_scope_complete is false, with reasons in target_scope_gaps, when the expansion stopped short. |
change | enum activity-change | — | Publication transition. Defaults to all substantive transitions. |
GET /api/v2/countries
17 accepted parameters — 11 core, 6 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time. |
date_end | date | — | Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day. |
country | enum country | — | Known country attribution. Evidence distinguishes location, actor origin, reporting and source association. |
basis | enum country_basis | default publication. With basis=reporting: cannot be combined with hour. Reporting has day precision; select publication for hourly changes. | publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. |
directory | boolean | — | Include every registered country, even those without observed activity. When omitted, returns the activity view rather than the paginated directory. |
q | string | Requires directory=true. Omit directory-only parameters for the complete activity map. | Country directory name or ISO code search. |
region | enum region | — | Registered geographic region whose member countries narrow the country activity or directory view. |
continent | enum continent | — | Registered continent whose member countries narrow the country activity or directory view. |
sort | enum country_directory_sort | Requires directory=true. Omit directory-only parameters for the complete activity map. With sort=rising: requires basis=reporting. Rising compares served Event counts, which only the reporting basis carries. | Directory order: most recently seen in reporting/publication activity (default), name alphabetically, events or stories descending with stable name ties, or rising. With rising, the served window is the recent window and the measure is Events: rising ranks by how far each row’s activity in the recent window rises above what its own previous 7 days predicted, scaled to the whole corpus so a part-filled day or a quiet weekend moves every row alike: (recent − expected) ÷ √(expected + 4). Rows with fewer than 3 recent records are not ranked. Each row carries a rising block with its recent, baseline and expected counts, the change multiple and both windows. Countries without a rising score follow by name. |
limit | limit | min 1, max 250. Requires directory=true. Omit directory-only parameters for the complete activity map. | Number of countries per directory page. |
offset | integer | min 0. Requires directory=true. Omit directory-only parameters for the complete activity map. | Number of directory countries to skip. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
time_basis | enum activity-time-basis | default published | Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged. |
hour | integer | min 0, max 23. Requires date_start and date_end to be equal when both are sent. An hour selects one UTC date. | UTC hour selecting a publication bucket on one UTC date. Rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day. |
include_event_metrics | boolean | With include_event_metrics=true: requires basis=reporting. | Include Event metric maxima with tied-country evidence, five AI-coded metric averages with scored Event counts, and per-country readings/linked identity counts. totals.entities_spotted counts distinct served identity/id-space pairs across the entire scoped Event set, never summed over countries; null when unavailable or not requested. Occurrence-date and location scope. Averages weight each finite scored canonical Event equally, independently of directory pagination. Unrestricted world averages and linked-identity totals include unlocated/global Events; geographic filters use location. Goldstein remains a signed maximum only. No scored observations gives null/count 0; unavailable context remains null. |
include_context | boolean | — | Include dated macro rollups for the selected geography, with same-period coverage and aggregation methods. Requires intelligence entitlement. |
include | enum country_include | Requires directory=true. Omit directory-only parameters for the complete activity map. | Status blocks for each returned directory row, read once for the whole page: gpr is the newest closed UTC day in the trailing 20 with an official Atlas GPR reading (Events lens; pulse 100 = the country’s own normal); posture is Atlas Posture over 30d (overall, internal, external); fundamentals is the latest World Bank annual inflation and GDP per person (PPP). Each block equals its endpoint’s answer, linked by evidence_url. Requires intelligence entitlement; a withheld or unavailable block is null with its status in meta.include_availability. Unknown values are null, never 0. |
story_search | string | Requires directory=true. Omit directory-only parameters for the complete activity map. Cannot be combined with q. q filters by country name; story_search ranks by a topic. | A TOPIC, not a country name: list the countries where the reporting about it happens. Runs the same search as /api/v2/stories?search= over this window and place, reads its first 100 Stories, and orders the directory rows of their location countries by those Stories, each weighted by how closely it matches ((search_score / best)^4). Each row’s story_search_match holds the count and that relevance sum; the directory’s own metrics are unchanged. This order replaces sort, echoed as story_search_relevance in applied_filters. meta.story_search.stories_request is the exact Stories call. |
GET /api/v2/countries/{iso3}
5 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
time_basis | enum activity-time-basis | default published | Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged. |
date_start | date | — | First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time. |
date_end | date | — | Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day. |
hour | integer | min 0, max 23. Requires date_start and date_end to be equal when both are sent. An hour selects one UTC date. | UTC hour selecting a publication bucket on one UTC date. Rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day. |
basis | enum country_basis | default publication. With basis=reporting: cannot be combined with hour. Reporting has day precision; select publication for hourly changes. | publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. |
GET /api/v2/events
52 accepted parameters — 12 core, 40 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | EVENT TIME — inclusive start of the window by when it HAPPENED (YYYY-MM-DD). Windows are capped at 30 inclusive days. Use consecutive date chunks; calendar months can exceed the cap. Follow the endpoint’s pagination guidance within each chunk. |
date_end | date | — | EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). |
days | duration | — | Calendar-date window ending today, in days (max 30). When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass days explicitly, or date_start/date_end, whenever the window matters. |
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Opaque pagination cursor taken from the previous response’s pagination.next_cursor. It binds the dates the first page served and the filters it was sent with: if one of those dates is re-served before you finish, or the cursor is sent with different filters, the next page answers 400 CURSOR_STALE: restart the walk from the first page. Authentication and current access are checked on every page. |
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. |
entity | enum entity_handle | — | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. |
category | enum event_category | case-insensitive | Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with subcategory: an impossible pair returns 400, never an empty 200. |
subcategory | csv | — | Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by category — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (Sexual violence is the measured example: its definition boundary sends nearly all such reporting to Attack). Before building a monitor on one code, measure it: GET /api/v2/events/summary?group_by=subcategory returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. |
significance_min | number | min 0, max 1 | Significance lower bound. |
search | string | — | Search text. The complete phrase is checked against name/title evidence and is also embedded for vector ranking; literal matches rank first and remaining results are conceptual neighbours. A person or organisation a short query names also brings in that entity’s rows that match the rest of the query. There is no boolean parser: a query shaped a OR b is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE. |
sort | enum event_sort | default significance. With sort=prominence|spread|rising: cannot be combined with search. prominence, spread and rising rank settled Events; rank a search by relevance or significance instead. | Ranking: significance (severity, default) · recent (newest first) · prominence (severity weighed with independent reports) · spread (outlets reporting the Event’s Story) · rising (coverage against the previous 7 days). spread and rising list one Event per Story first. A bare search ranks by relevance. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
observed_start | date_or_instant | — | Inclusive UTC date or instant: Event coded_at or Story updated_at. |
observed_end | date_or_instant | — | Exclusive UTC date or instant: Event coded_at or Story updated_at. |
region | enum region | — | Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules. |
continent | enum continent | — | Continent expanded to its member ISO-3 countries; applied through the same country matching rules. |
country_match | enum country_match | default location_or_actor_origin | Which definition of “in this country” the country / region / continent filters use. Applies to region and continent too, since both expand into the same country set. Note that group_by=country buckets on the event’s own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass country_match=location when you need the two to agree. |
admin1 | csv | — | State or province (admin1), not a city. 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. The box is used for index pruning and rows are refined by true great-circle distance. |
radius_km | number | — | Distance in kilometres from the selected point for geographic proximity matching. |
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_family | enum entity_family | default expand | Which canonical ids the handle stands for. expand (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as applied_filters.entity_ids_expanded. exact restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts. |
target_type | enum target_type | Requires target_ids. With target_type=facility: requires related_scope=connected unless nearby_radius_km is sent. A facility has no news identity of its own: send related_scope=connected for reporting about its identified owners, or nearby_radius_km for the Events within that distance of it. | Typed selected root for a shared connected scope: entity or facility. |
target_ids | csv | Requires target_type. Cannot be combined with entity. Use either entity or a typed target scope. | Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. |
related_scope | enum related_scope | default direct. Requires target_type and target_ids. | direct matches the selected targets only. connected also matches, for an entity, the companies it owns or consolidates: subsidiaries its SEC Exhibit 21 lists and its GLEIF consolidated children, direct or naming it as ultimate parent, down five levels and up to 250 companies per target. Only companies that are themselves registry entities are added, and an entity target expands only from its e_… registry id. For a facility, connected adds its identified owners and their parent companies. applied_filters.relationship_paths lists each added company and the relationship that added it; applied_filters.target_scope_complete is false, with reasons in target_scope_gaps, when the expansion stopped short. |
nearby_radius_km | number | min 1, max 2000 | Opt-in proximity for a facility target scope. Matches Events near any selected facility; this is separate from owner coverage and requires target_type=facility with related_scope=direct. |
office | enum office_id | — | Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (Q…) or the p_… id /api/v2/offices serves. Resolves to every holder whose published term overlaps the window (or office_as_of, when sent), then scopes exactly as entity=<those holders> would — a row is returned if ANY holder matches, and it is UNIONED with entity= when both are sent. A name is refused with 400; resolve it with GET /api/v2/offices?q= first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so applied_filters.office_holders discloses how many of the roster are bridged_to_news versus unbridged — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office’s real coverage rather than a measurement of it. Each matched row carries entity_link.via: "office" with entity_link.entity naming the HOLDER (a spine id), not the office. |
office_as_of | date | — | VALID TIME for office= — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher’s start/end clock, not what we knew then: it is NOT the knowledge-time as_of and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in applied_filters.office_holders.undated_excluded), never fabricated. Ignored without office. |
significance_max | number | min 0, max 1 | Significance upper bound. |
confidence_min | number | min 0, max 1 | Confidence lower bound. |
confidence_max | number | min 0, max 1 | Confidence upper bound. |
goldstein_scale_min | number | min -10, max 10 | Goldstein scale lower bound. Only CAMEO+ POLITICAL and conflict-family Events carry it, so a bound excludes Events from every other domain. |
goldstein_scale_max | number | min -10, max 10 | Goldstein scale upper bound. Only CAMEO+ POLITICAL and conflict-family Events carry it, so a bound excludes Events from every other domain. |
magnitude_min | number | min 0, max 10 | Magnitude lower bound. 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. 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. 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. 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. 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. 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. 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. 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. |
geo_precision_max | number | min 1, max 3 | Geo precision upper bound. |
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”. No filter finds deadly CAMEO+ events, because that family records no death count. To screen both families by importance use significance_min, which ranks them on one scale (deaths count in it for conflict events only), or goldstein_scale_max where Goldstein is defined — it is signed, so goldstein_scale_max=-5 selects the strongly conflictual end. Read fatalities off the card to tell a measured 0 from an absent observable. |
civilian_targeting | boolean | — | Restrict to events coded as targeting civilians. |
languages | csv | — | Source-language filter (ISO 639-1/2) on the linked Story’s coverage. |
include_images | boolean | default false | Attach article images to each card. Off by default. When enabled, entity thumbnails are also included unless include_entity_images=false. |
include_entity_images | boolean | default true | Include entity thumbnails when include_images=true. Defaults to true, but has no effect while include_images is false or omitted. Pass false to skip the additional Wikipedia lookups while retaining article images. |
GET /api/v2/stories
35 accepted parameters — 11 core, 24 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | EVENT TIME — inclusive start of the window by when it HAPPENED (YYYY-MM-DD). Windows are capped at 30 inclusive days. Use consecutive date chunks; calendar months can exceed the cap. Follow the endpoint’s pagination guidance within each chunk. |
date_end | date | — | EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). |
days | duration | — | Calendar-date window ending today, in days (max 30). When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass days explicitly, or date_start/date_end, whenever the window matters. |
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Opaque pagination cursor taken from the previous response’s pagination.next_cursor. It binds the dates the first page served and the filters it was sent with: if one of those dates is re-served before you finish, or the cursor is sent with different filters, the next page answers 400 CURSOR_STALE: restart the walk from the first page. Authentication and current access are checked on every page. |
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. Combined with a filter on a Story’s Events (category, subcategory, admin1, bbox, civilian_targeting), country keeps the Event-only definition. Attribution begins 2026-07; earlier windows are Event-derived only. |
entity | enum entity_handle | — | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. |
search | string | — | Search text. The complete phrase is checked against name/title evidence and is also embedded for vector ranking; literal matches rank first and remaining results are conceptual neighbours. A person or organisation a short query names also brings in that entity’s rows that match the rest of the query. There is no boolean parser: a query shaped a OR b is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE. |
story_category | enum story_category | — | Story-level category. Comma-separate for OR. |
article_count_min | number | min 0 | Minimum article count. |
sort | enum story_sort | default significance. With sort=spread|rising: cannot be combined with search. spread and rising rank settled Stories; rank a search by relevance or significance instead. | Ranking: significance (size, default) · recent (latest update first) · spread (distinct outlets) · rising (articles against the thread’s previous 7 days; a new thread ranks on its size). A bare search ranks by relevance. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
observed_start | date_or_instant | — | Inclusive UTC date or instant: Event coded_at or Story updated_at. |
observed_end | date_or_instant | — | Exclusive UTC date or instant: Event coded_at or Story updated_at. |
region | enum region | — | Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules. |
continent | enum continent | — | Continent expanded to its member ISO-3 countries; applied through the same country matching rules. |
country_match | enum country_match | default location_or_actor_origin | Which definition of “in this country” the country / region / continent filters use. Applies to region and continent too, since both expand into the same country set. Note that group_by=country buckets on the event’s own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass country_match=location when you need the two to agree. |
admin1 | csv | — | State or province (admin1), not a city. Discover valid values with GET /api/v2/geo/admin1?country=. |
bbox | bbox | — | Bounding box lat_min,lon_min,lat_max,lon_max. |
entity_family | enum entity_family | default expand | Which canonical ids the handle stands for. expand (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as applied_filters.entity_ids_expanded. exact restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts. |
target_type | enum target_type | Requires target_ids. With target_type=facility: requires related_scope=connected unless nearby_radius_km is sent. A facility has no news identity of its own: send related_scope=connected for its identified owners’ Stories, or nearby_radius_km for the Stories behind the Events within that distance of it. | Typed selected root for a shared connected scope: entity or facility. |
target_ids | csv | Requires target_type. Cannot be combined with entity. Use either entity or a typed target scope. | Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. |
related_scope | enum related_scope | default direct. Requires target_type and target_ids. | direct matches the selected targets only. connected also matches, for an entity, the companies it owns or consolidates: subsidiaries its SEC Exhibit 21 lists and its GLEIF consolidated children, direct or naming it as ultimate parent, down five levels and up to 250 companies per target. Only companies that are themselves registry entities are added, and an entity target expands only from its e_… registry id. For a facility, connected adds its identified owners and their parent companies. applied_filters.relationship_paths lists each added company and the relationship that added it; applied_filters.target_scope_complete is false, with reasons in target_scope_gaps, when the expansion stopped short. |
nearby_radius_km | number | min 1, max 250. Requires target_type=facility; cannot be combined with cursor. | Opt-in proximity for a facility target scope: the Stories behind the Events within this many km of the facility (up to 100 Events, 50 Stories, one page). Requires target_type=facility with related_scope=direct. Proximity is not participation; meta.facility_nearby names the Events call. |
office | enum office_id | — | Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (Q…) or the p_… id /api/v2/offices serves. Resolves to every holder whose published term overlaps the window (or office_as_of, when sent), then scopes exactly as entity=<those holders> would — a row is returned if ANY holder matches, and it is UNIONED with entity= when both are sent. A name is refused with 400; resolve it with GET /api/v2/offices?q= first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so applied_filters.office_holders discloses how many of the roster are bridged_to_news versus unbridged — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office’s real coverage rather than a measurement of it. Each matched row carries entity_link.via: "office" with entity_link.entity naming the HOLDER (a spine id), not the office. |
office_as_of | date | — | VALID TIME for office= — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher’s start/end clock, not what we knew then: it is NOT the knowledge-time as_of and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in applied_filters.office_holders.undated_excluded), never fabricated. Ignored without office. |
category | enum event_category | case-insensitive | Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with subcategory: an impossible pair returns 400, never an empty 200. On Stories this filters the LINKED EVENTS. Passing a Story cluster label here (for example cameoplus_political) is a legacy alias for story_category and is applied as one — a materially different filter, so prefer story_category for a Story label and keep category for linked-event taxonomy. applied_filters reports which one received it. |
subcategory | csv | — | Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by category — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (Sexual violence is the measured example: its definition boundary sends nearly all such reporting to Attack). Before building a monitor on one code, measure it: GET /api/v2/events/summary?group_by=subcategory returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. |
has_events | boolean | — | Restrict to Stories that have (or have not) linked Events. |
has_fatalities | boolean | — | Restrict to Stories whose linked conflict Events report deaths (true) or report none (false). 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 either: it returns Stories whose linked conflict Events that match your place and category filters report no deaths (“reported non-lethal”). A Story with no such conflict Event, including one whose Events are all CAMEO+, matches neither value: its fatalities and has_fatalities are null. Stories publish no metric filters, so for a cross-family severity screen query /api/v2/events — which does — and follow story_refs back. |
civilian_targeting | boolean | — | Restrict to Stories whose linked Events target civilians. |
article_count_max | number | min 0 | Maximum article count. |
languages | csv | — | Coverage-language filter (ISO 639-1/2). |
include_images | boolean | default false | Attach article images to each card. Off by default. When enabled, entity thumbnails are also included unless include_entity_images=false. |
include_entity_images | boolean | default true | Include entity thumbnails when include_images=true. Defaults to true, but has no effect while include_images is false or omitted. Pass false to skip the additional Wikipedia lookups while retaining article images. |
related | boolean | — | Attach related Stories. |
GET /api/v2/events/summary
47 accepted parameters — 11 core, 36 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | EVENT TIME — inclusive start of the window by when it HAPPENED (YYYY-MM-DD). Windows are capped at 30 inclusive days. Use consecutive date chunks; calendar months can exceed the cap. Follow the endpoint’s pagination guidance within each chunk. |
date_end | date | — | EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). |
days | duration | — | Calendar-date window ending today, in days (max 30). When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass days explicitly, or date_start/date_end, whenever the window matters. |
limit | limit | min 1, max 500, default 50 | Maximum number of BUCKETS returned (not rows). Default 50, max 500. There is no cursor on this endpoint, so a result at the limit may be truncated — widen the limit or narrow the window. |
group_by | enum event_group_by | default date | The dimension to aggregate over. Every dimension reconciles to the same total. |
country | csv | case-insensitive | Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event’s own location OR either actor’s origin country by default, so a result can include events that happened elsewhere — set country_match to narrow it to location only. The definition in force is echoed as applied_filters.country_match. |
entity | enum entity_handle | — | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. |
category | enum event_category | case-insensitive | Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with subcategory: an impossible pair returns 400, never an empty 200. |
subcategory | csv | — | Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by category — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (Sexual violence is the measured example: its definition boundary sends nearly all such reporting to Attack). Before building a monitor on one code, measure it: GET /api/v2/events/summary?group_by=subcategory returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. |
significance_min | number | min 0, max 1 | Significance lower bound. |
search | string | — | Text to count. A query that is exactly one person or organisation name counts that entity’s rows (disclosed in applied_filters.normalized); any other text counts rows whose Event title/summary or Story title contains it as whole words, ignoring case and accents: port congestion does not count airport congestion, and sao paulo counts São Paulo. In Chinese, Japanese, Thai, Lao, Khmer and Burmese, which do not separate words with spaces, the text may match inside a longer word. No stemming or Boolean parsing: flood does not count floods. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
observed_start | date_or_instant | — | Inclusive UTC date or instant: Event coded_at or Story updated_at. |
observed_end | date_or_instant | — | Exclusive UTC date or instant: Event coded_at or Story updated_at. |
region | enum region | — | Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules. |
continent | enum continent | — | Continent expanded to its member ISO-3 countries; applied through the same country matching rules. |
country_match | enum country_match | default location_or_actor_origin | Which definition of “in this country” the country / region / continent filters use. Applies to region and continent too, since both expand into the same country set. Note that group_by=country buckets on the event’s own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass country_match=location when you need the two to agree. |
admin1 | csv | — | State or province (admin1), not a city. 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. The box is used for index pruning and rows are refined by true great-circle distance. |
radius_km | number | — | Distance in kilometres from the selected point for geographic proximity matching. |
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_family | enum entity_family | default expand | Which canonical ids the handle stands for. expand (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as applied_filters.entity_ids_expanded. exact restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts. |
target_type | enum target_type | Requires target_ids. With target_type=facility: requires related_scope=connected. A facility has no news identity of its own and the summary takes no radius: send related_scope=connected to summarize its identified owners’ reporting, or list the Events near it with /api/v2/events and nearby_radius_km. | Typed selected root for a shared connected scope: entity or facility. |
target_ids | csv | Requires target_type. Cannot be combined with entity. Use either entity or a typed target scope. | Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. |
related_scope | enum related_scope | default direct. Requires target_type and target_ids. | direct matches the selected targets only. connected also matches, for an entity, the companies it owns or consolidates: subsidiaries its SEC Exhibit 21 lists and its GLEIF consolidated children, direct or naming it as ultimate parent, down five levels and up to 250 companies per target. Only companies that are themselves registry entities are added, and an entity target expands only from its e_… registry id. For a facility, connected adds its identified owners and their parent companies. applied_filters.relationship_paths lists each added company and the relationship that added it; applied_filters.target_scope_complete is false, with reasons in target_scope_gaps, when the expansion stopped short. |
office | enum office_id | — | Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (Q…) or the p_… id /api/v2/offices serves. Resolves to every holder whose published term overlaps the window (or office_as_of, when sent), then scopes exactly as entity=<those holders> would — a row is returned if ANY holder matches, and it is UNIONED with entity= when both are sent. A name is refused with 400; resolve it with GET /api/v2/offices?q= first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so applied_filters.office_holders discloses how many of the roster are bridged_to_news versus unbridged — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office’s real coverage rather than a measurement of it. Each matched row carries entity_link.via: "office" with entity_link.entity naming the HOLDER (a spine id), not the office. |
office_as_of | date | — | VALID TIME for office= — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher’s start/end clock, not what we knew then: it is NOT the knowledge-time as_of and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in applied_filters.office_holders.undated_excluded), never fabricated. Ignored without office. |
significance_max | number | min 0, max 1 | Significance upper bound. |
confidence_min | number | min 0, max 1 | Confidence lower bound. |
confidence_max | number | min 0, max 1 | Confidence upper bound. |
goldstein_scale_min | number | min -10, max 10 | Goldstein scale lower bound. Only CAMEO+ POLITICAL and conflict-family Events carry it, so a bound excludes Events from every other domain. |
goldstein_scale_max | number | min -10, max 10 | Goldstein scale upper bound. Only CAMEO+ POLITICAL and conflict-family Events carry it, so a bound excludes Events from every other domain. |
magnitude_min | number | min 0, max 10 | Magnitude lower bound. 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. 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. 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. 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. 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. 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. 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. 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. |
geo_precision_max | number | min 1, max 3 | Geo precision upper bound. |
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”. No filter finds deadly CAMEO+ events, because that family records no death count. To screen both families by importance use significance_min, which ranks them on one scale (deaths count in it for conflict events only), or goldstein_scale_max where Goldstein is defined — it is signed, so goldstein_scale_max=-5 selects the strongly conflictual end. Read fatalities off the card to tell a measured 0 from an absent observable. |
civilian_targeting | boolean | — | Restrict to events coded as targeting civilians. |
languages | csv | — | Coverage-language filter (ISO 639-1/2) on the underlying articles. |
GET /api/v2/stories/summary
31 accepted parameters — 10 core, 21 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | EVENT TIME — inclusive start of the window by when it HAPPENED (YYYY-MM-DD). Windows are capped at 30 inclusive days. Use consecutive date chunks; calendar months can exceed the cap. Follow the endpoint’s pagination guidance within each chunk. |
date_end | date | — | EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). |
days | duration | — | Calendar-date window ending today, in days (max 30). When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass days explicitly, or date_start/date_end, whenever the window matters. |
limit | limit | min 1, max 500, default 50 | Maximum number of BUCKETS returned (not rows). Default 50, max 500. There is no cursor on this endpoint, so a result at the limit may be truncated — widen the limit or narrow the window. |
group_by | enum story_group_by | default date | The dimension to aggregate over. Country buckets overlap when country_attribution=all; use group_by=date for distinct totals. |
country | 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. Combined with a filter on a Story’s Events (category, subcategory, admin1, bbox, civilian_targeting), country keeps the Event-only definition. Attribution begins 2026-07; earlier windows are Event-derived only. |
entity | enum entity_handle | — | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. |
search | string | — | Text to count. A query that is exactly one person or organisation name counts that entity’s rows (disclosed in applied_filters.normalized); any other text counts rows whose Event title/summary or Story title contains it as whole words, ignoring case and accents: port congestion does not count airport congestion, and sao paulo counts São Paulo. In Chinese, Japanese, Thai, Lao, Khmer and Burmese, which do not separate words with spaces, the text may match inside a longer word. No stemming or Boolean parsing: flood does not count floods. |
story_category | enum story_category | — | Story-level topic, comma-separated for OR. Distinct from the EVENT taxonomy that category filters. |
article_count_min | number | min 1 | Lower bound on the number of source articles behind a Story. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
observed_start | date_or_instant | — | Inclusive UTC date or instant: Event coded_at or Story updated_at. |
observed_end | date_or_instant | — | Exclusive UTC date or instant: Event coded_at or Story updated_at. |
country_attribution | enum story_country_attribution | default primary | For group_by=country: primary preserves one primary country per Story; all counts each Story under every authoritative country attribution or linked Event location/actor origin, using the same country_match and other filters as the Stories list. Explicit geographic filters also restrict the emitted country buckets. Buckets overlap and must not be summed as a global total. Other groupings ignore this option. |
region | enum region | — | Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules. |
continent | enum continent | — | Continent expanded to its member ISO-3 countries; applied through the same country matching rules. |
country_match | enum country_match | default location_or_actor_origin | Which definition of “in this country” the country / region / continent filters use. Applies to region and continent too, since both expand into the same country set. Note that group_by=country buckets on the event’s own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass country_match=location when you need the two to agree. |
admin1 | csv | — | State or province (admin1), not a city. Discover valid values with GET /api/v2/geo/admin1?country=. |
bbox | bbox | — | Bounding box lat_min,lon_min,lat_max,lon_max. |
entity_family | enum entity_family | default expand | Which canonical ids the handle stands for. expand (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as applied_filters.entity_ids_expanded. exact restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts. |
target_type | enum target_type | Requires target_ids. With target_type=facility: requires related_scope=connected. A facility has no news identity of its own and the summary takes no radius: send related_scope=connected to summarize its identified owners’ Stories, or list the Stories near it with /api/v2/stories and nearby_radius_km. | Typed selected root for a shared connected scope: entity or facility. |
target_ids | csv | Requires target_type. Cannot be combined with entity. Use either entity or a typed target scope. | Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. |
related_scope | enum related_scope | default direct. Requires target_type and target_ids. | direct matches the selected targets only. connected also matches, for an entity, the companies it owns or consolidates: subsidiaries its SEC Exhibit 21 lists and its GLEIF consolidated children, direct or naming it as ultimate parent, down five levels and up to 250 companies per target. Only companies that are themselves registry entities are added, and an entity target expands only from its e_… registry id. For a facility, connected adds its identified owners and their parent companies. applied_filters.relationship_paths lists each added company and the relationship that added it; applied_filters.target_scope_complete is false, with reasons in target_scope_gaps, when the expansion stopped short. |
office | enum office_id | — | Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (Q…) or the p_… id /api/v2/offices serves. Resolves to every holder whose published term overlaps the window (or office_as_of, when sent), then scopes exactly as entity=<those holders> would — a row is returned if ANY holder matches, and it is UNIONED with entity= when both are sent. A name is refused with 400; resolve it with GET /api/v2/offices?q= first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so applied_filters.office_holders discloses how many of the roster are bridged_to_news versus unbridged — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office’s real coverage rather than a measurement of it. Each matched row carries entity_link.via: "office" with entity_link.entity naming the HOLDER (a spine id), not the office. |
office_as_of | date | — | VALID TIME for office= — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher’s start/end clock, not what we knew then: it is NOT the knowledge-time as_of and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in applied_filters.office_holders.undated_excluded), never fabricated. Ignored without office. |
category | enum event_category | case-insensitive | Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with subcategory: an impossible pair returns 400, never an empty 200. On Stories this filters the LINKED EVENTS. Passing a Story cluster label here (for example cameoplus_political) is a legacy alias for story_category and is applied as one — a materially different filter, so prefer story_category for a Story label and keep category for linked-event taxonomy. applied_filters reports which one received it. |
subcategory | csv | — | Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by category — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (Sexual violence is the measured example: its definition boundary sends nearly all such reporting to Attack). Before building a monitor on one code, measure it: GET /api/v2/events/summary?group_by=subcategory returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. |
has_events | boolean | — | Restrict to Stories with at least one linked Event. |
has_fatalities | boolean | — | Restrict to Stories whose linked conflict Events report deaths (true) or report none (false). 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 either: it returns Stories whose linked conflict Events that match your place and category filters report no deaths (“reported non-lethal”). A Story with no such conflict Event, including one whose Events are all CAMEO+, matches neither value: its fatalities and has_fatalities are null. Stories publish no metric filters, so for a cross-family severity screen query /api/v2/events — which does — and follow story_refs back. |
civilian_targeting | boolean | — | Restrict to Stories with civilian-targeting events. |
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. |
GET /api/v2/facilities
26 accepted parameters — 7 core, 19 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
q | string | — | Facility name. Default lexical mode keeps case-insensitive substring matching. Ports are registered under their place name, so “Port of Rotterdam”, “Rotterdam port”, “Rotterdam seaport” and “Rotterdam harbour” also match ports whose name contains “Rotterdam”, and “Meta Hyperion data center” matches data centers whose name contains “Meta Hyperion”; the literal text always matches too. Opt-in search_mode=fuzzy suggests names with matching prefixes or small spelling errors; every query token must match a name token. These are selectable candidates, not resolved site identity. No embedding or inference runs. |
type | enum facility_type | — | Facility type. Comma-separate for OR. |
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. With group_pipelines=true a multi-country pipeline matches when any of its segments does, and its row still lists every country in countries. |
entity | enum entity_handle | — | The owner: an entity id, or a name resolved to one entity through the shared entity resolver. Use owner_search to match owner names loosely instead. |
sort | enum facility_sort | — | Ordering: name (the default without q) · capacity_desc · capacity_asc · recent (directory updates) · country · relevance (requires q; the default when q or search is sent without sort: the exact name first, then a place named with its type word, such as the port “Rotterdam” for “Port of Rotterdam”, then names containing the text, then token distance) · news_activity. News activity ranks the entire filtered directory by direct-owner Event count first, then the distinct owner/nearby Event union over seven recent days, matched to explicit owner identities on Event cards or within 25 km; overlaps count once. Parent rollups are excluded. Counts and exact served dates are disclosed; nearby reporting does not establish a site incident. rising ranks by the same owner/nearby Event union over the last two served days against the seven before: rising ranks by how far each row’s activity in the recent window rises above what its own previous 7 days predicted, scaled to the whole corpus so a part-filled day or a quiet weekend moves every row alike: (recent − expected) ÷ √(expected + 4). Rows with fewer than 3 recent records are not ranked. Each row carries a rising block with its recent, baseline and expected counts, the change multiple and both windows. Sites without a rising score follow by news activity. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
granularity | string | default site | site (default) returns one canonical physical site; unit exposes source registry units. |
group_pipelines | boolean | With group_pipelines=true: requires granularity=site. Registry units are never grouped. | Opt-in. true returns a GEM gas or oil pipeline whose segments span more than one country as one row, with countries, segment_count and segments, disclosed in meta.multi_country_assets. Default: one row per canonical site, exactly as GEM publishes each segment. Site granularity only. |
story_search | string | Cannot be combined with q, entity or owner_search. story_search chooses the sites from the reporting; q matches a site name. | A TOPIC, not a site name: list the sites the reporting about it points to. Reads the same first 100 Stories /api/v2/stories?search= returns for this place over 7 days. A Story points to a site when it happened within 25 km of it (by its linked Events) and its titles name the site (its whole distinctive name, or part of it with its kind: “Tarragona port”), or when it names one of the site’s owners (one of the top 10 linked organizations in at least two of those Stories) and the owner holds at most 5 sites, or the Story names the kind of site it holds (“lithium mine”), or it happened within 25 km of that site. Each Story is shared among the sites it points to, and sites are ordered by the sum (story_search_match.relevance, at least 0.05); this order replaces sort. meta.story_search names the owners and the places used. |
search_mode | enum facility_name_search_mode | default lexical | lexical (default) preserves substring search. fuzzy requires 2–200 characters and 1–12 name tokens; small typos and token prefixes are supported. Use sort=relevance to put literal matches before fuzzy suggestions. Other category/geography filters stay exact. |
class | enum facility_class | — | Broad facility class; expanded to its member types. |
source | enum facility_source_silo | — | Contributing source membership; keeps all observations for each matching canonical site. |
commodity | enum facility_commodity | — | Observed current-directory commodity values are suggestions, not a closed vocabulary; comma-separate for OR. New values are accepted. A mine and a refinery remain separate assets. |
participant_entity | enum entity_handle | — | Match a resolved entity named in a source participant record. This is separate from entity and owner filters; a role assertion does not establish ownership. |
participant_role | string | — | Exact source-reported participant role. Open vocabulary (for example operator or tenant); this does not establish ownership. |
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. |
region | enum region | — | Region; expanded to member countries. |
continent | enum continent | — | Continent; expanded to member countries. |
owner_search | string | — | Owner name to match loosely, including names that resolve to no entity. Use entity for one resolved owner. |
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). |
bbox | bbox | — | Bounding box lat_min,lon_min,lat_max,lon_max. |
near | point | — | Point proximity lat,lon,radius_km, refined by true great-circle distance. Note this is the three-part grammar — /api/v2/events takes near=lat,lon with a separate radius_km. |
GET /api/v2/facilities/{facility_id}
Takes no query parameters.
GET /api/v2/facilities/{facility_id}/context
6 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
days | duration | default 30 | Owner-coverage window in days, max 30. |
date_start | date | — | Explicit start of the owner-coverage window. |
date_end | date | — | Explicit end of the owner-coverage window. |
limit | limit | min 1, max 50, default 10 | Number of owner-linked Events to attach to this facility context. |
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. nearby attaches Events within radius_km and their linked Stories. Nearby reporting is a geographic lead, not a confirmed incident at the site. |
radius_km | number | min 1, max 250, default 25 | Distance in kilometres for optional nearby Event screening. Source coordinate precision is disclosed; nearby reporting is a lead, not a confirmed incident at the facility. |
GET /api/v2/intelligence/gpr
13 accepted parameters — 7 core, 6 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
level | enum atlas_level | default world | Spatial aggregation of the risk series: the world or a selected continent, region or country. |
geo | string | — | Place identifier appropriate for level; required when level is continent, region, or country and omitted for world. |
window | duration | min 1, max 30 | Length of the trailing display window in days. Defaults to 7 only when no explicit dates are supplied; omit when sending date_start/date_end. |
date_start | date | — | First observation date. |
date_end | date | — | Last observation date. |
limit | limit | min 1, max 100, default 100 | Number of records to return on this page; pagination describes how to continue. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
construction | enum atlas_gpr_construction | default own_coverage | Own-coverage series or the count-weighted world-corpus reference. The world-corpus reference uses the gpr variant/metric and attention weighting. |
variant | enum atlas_gpr_variant | — | GPR lens. Defaults to gpr for world_corpus and events otherwise. |
component | enum atlas_gpr_component | default all | Component of the selected risk variant used for decomposition; use get_parameter_options with the variant to discover compatible components. |
metric | enum atlas_gpr_metric | default gpr | Measure to read from the returned geopolitical-risk series; select it for the chosen construction and variant. |
weighting | enum atlas_weighting | default attention | How country observations contribute to the regional or world aggregate; attention weights by coverage, equal gives countries equal weight. |
as_of | date | — | Point-in-time vintage. |
GET /api/v2/intelligence/posture
8 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
country | string | — | Country ISO3 shortcut. Takes precedence over geo. |
level | enum atlas_level | default country | Spatial aggregation of the structural and dynamic posture evidence. |
geo | string | — | Place appropriate to level, using a country ISO-3 code or a returned region/continent name. For level=world, omit geo; a supplied country selects the country view. |
scope | enum atlas_posture_scope | default all | Dynamic evidence scope to include in posture calculations. Omission includes all scopes. |
window | enum atlas_posture_window | default 30d | Duration of the dynamic Event window. |
weighting | enum atlas_weighting | default attention | How country observations contribute to the geographic rollup; a country view is not an aggregate and the response discloses fallback behavior. |
date | date | — | Window end date. Omission uses the latest computed observations. |
as_of | date | — | Observation vintage cutoff. Structural inputs and normalization are not a historical snapshot; inspect response limitations. |
GET /api/v2/intelligence/coverage
4 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
window | duration | min 1, max 30, default 30 | Trailing coverage-measurement window in days, 1–30, ending today. Both 30 and 30d are accepted, so the same spelling works here and on /api/v2/intelligence/posture. |
tier | enum atlas_coverage_tier | case-insensitive | Return only countries in this coverage tier. depth = dense enough for a country-level Posture reading (the curated servable set); thin = some coverage but below that floor; none = no coded events in the window at all. |
region | string | — | Return only countries in this region, matched case-insensitively against the region name each row carries. |
continent | string | — | Return only countries on this continent, matched case-insensitively against the continent name each row carries. |
GET /api/v2/filings/resolve
5 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
q | string | — | Company-name query. |
ticker | identifier | — | Exact ticker symbol. |
cik | identifier | — | SEC CIK, with or without zero padding. |
limit | limit | min 1, max 100, default 10 | Maximum candidates returned. |
min_score | number | min 0, max 1 | Minimum fuzzy-name candidate score. |
GET /api/v2/screening/match
8 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
q | string | — | Counterparty name. |
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. |
include_exposure | boolean | default true | Attach ownership-chain exposure context. |
limit | limit | min 1, max 100, default 25 | Maximum matched entities returned. |
nationality | csv | — | Nationality / citizenship of the subject as ISO-3 codes, comma-separated (IRN,IRQ). Evidence only: compared against each candidate’s country_iso3 and reported per candidate as evidence.nationality (match | mismatch | unknown); it never filters retrieval and never rejects on its own, because list country fields are inconsistently populated (see the coverage warning on /api/v2/lists/entries). An unresolvable code returns 400 INVALID_COUNTRY. |
birth_year | integer | min 1900 | Year of birth of the subject (1900 to the current year). Evidence only, compared with a ±1 tolerance because lists publish approximate and circa dates: a candidate whose recorded year contradicts it beyond that tolerance is moved to rejected_candidates with decision_evidence: birth_year_mismatch; agreement is reported as evidence.birth_year: match and raises confidence only together with an exact name; a candidate with no recorded year is unknown and remains a candidate. There is deliberately NO date-of-birth parameter: the served person field is a birth YEAR (schema 171 stores year only, never a date), so a full DOB could not be compared to anything and would only invite callers to send PII we do not hold. |
GET /api/v2/exposure
16 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: a source_key from GET /api/v2/lists (rows with ingested: true), or state_owned or cn_state. Case-insensitive. |
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_search | string | — | Fuzzy entity resolver query. |
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 | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
GET /api/v2/share-of-voice
16 accepted parameters — 7 core, 9 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
query | string | — | Semantic denominator query. |
entity | csv | — | Entities to measure, as ids (e_…, wiki:…) or names, comma-separated. Each one resolves to a canonical entity; resolved_entities and unresolved_terms show how. |
date_start | date | — | First date of the comparison window, YYYY-MM-DD. |
date_end | date | — | Last date of the comparison window, YYYY-MM-DD. |
days | duration | — | Length in days of the trailing comparison window; it ends at date_end, or today. |
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; pagination describes how to continue. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
topic | string | — | Lexical denominator topic. |
category | string | — | Story or event category denominator. |
country | string | — | Country denominator. Accepts an English name, ISO-2, or ISO-3. A Story matches when its own attributed countries include the value, or a linked Event is located there, or either linked Event actor originates there. |
region | string | — | Region denominator. |
continent | string | — | Continent restricting the Story/Event comparison denominator to its geographic coverage. |
languages | csv | — | Language-code denominator. |
source_set | csv | — | Source denominator. all selects the complete served Story corpus in the requested window; otherwise pass one or more article domains such as reuters.com. |
run_id | identifier | — | Materialized analytics run identifier returned by share_of_voice; selects that computation. |
denominator_hash | identifier | — | Denominator identity returned by a previous share_of_voice computation; reuses that exact comparison baseline. |
GET /api/v2/stories/{story_id}/articles
8 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | First Story date of the window, YYYY-MM-DD. |
date_end | date | — | Last Story date of the window, YYYY-MM-DD. |
days | duration | default 14 | Trailing date window, in days. |
limit | limit | min 1, max 100, default 25 | Maximum articles returned. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
include_images | boolean | — | Attach resolved article images. |
languages | csv | — | Source-language filter: comma-separated language codes. |
publisher_country_iso3 | string | — | Known publisher-country filter; unknown publishers are never guessed. |
GET /api/v2/filings/relations
10 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
entity | identifier | — | The named company: a registry e_ id, or a news wiki:/llm: id bridged to the registry. Rows stored under any id that has since merged into it are included. A bare name is refused (INVALID_ENTITY_ID); resolve it first with /api/v2/filings/resolve?q= (its entity_id) or /api/v2/entities?q=. |
rel_type | enum filings_rel_type | — | Relation kinds to read, comma-separated. Omitted: supplier,customer,partner,counterparty. subsidiary reads the filers whose Exhibit 21 lists the company. |
match | enum filings_relation_match | default resolved. With match=name: requires entity. a name match needs the entity whose registry names it compares | resolved admits relations tied to the entity by a stored registry id or by the table’s name consensus. name also admits relations whose unresolved object name equals one of the entity’s registry names (after dropping corporate suffixes and a trailing acronym in parentheses) and no other registry entity’s. Those rows carry resolution_source: name_match and matched_name; an exact name is evidence, not proof, so read the quote. |
group_by | enum filings_relation_group_by | default relation | relation: one row per stored relation (a filer can name a company in several filings and sections). filer: one row per filer and relation kind, carrying its most recent, most confident relation plus relation_count, filing_count, first_file_date and last_file_date. |
country | csv | — | Counterparty (object) country, comma-separated: a name, ISO-2 or ISO-3 code. Matches the country the extraction recorded for the named company, not the filer’s country. |
region | enum region | case-insensitive | Counterparty region, expanded to its countries and applied like country. |
continent | enum continent | case-insensitive | Counterparty continent, expanded to its countries and applied like country. |
commodity | string | — | What is supplied, as the extraction recorded it (wafers, memory, crude oil …): a case-insensitive substring of object_commodity, at least 3 characters. Open vocabulary; most customer and partner relations carry none. |
limit | limit | min 1, max 200, default 50 | Rows per page (relations, or filers with group_by=filer); page on with cursor. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
GET /api/v2/lists
4 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
source | enum list_source_key | case-insensitive | Restrict the catalogue to one source_key. Case-insensitive. |
category | enum list_category | case-insensitive | Return only sources of this kind. sanctions and export_control are the two categories that count toward the sanctions exposure lens; debarment, wanted, maritime and domestic_terror are catalogued and screenable but are not sanctions. |
jurisdiction | string | — | Issuer jurisdiction code (US, EU, UN, GB, CN, AU, …), matched case-insensitively. |
cadence | enum list_cadence | — | Our refresh cadence for the source. Observed vocabulary — matched exactly, case-sensitively. |
GET /api/v2/lists/entries
14 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
list | enum list_source_key | case-insensitive | The list to search, by source_key. Case-insensitive. Find keys with GET /api/v2/lists: every row with ingested: true is accepted. |
q | string | — | Case-insensitive substring over the entry name, its normalized form and every alias. |
country | string | — | Country of the entry — a name, ISO-2 or ISO-3. Matched on the structured field OR the trailing ISO-2 token of an address, see coverage_warning. |
region | string | — | Region expanded to its countries (Eastern Europe). |
continent | string | — | Continent expanded to its countries (Asia). |
program | string | — | Sanctions programme code, matched case-insensitively (UKRAINE-EO13662). |
entity | entity | — | Only entries resolved to this entity — an e_ spine id or a wiki: news id, collapsed through the arbiter. An id the registry has never heard of answers 400 UNRESOLVED_ENTITY_ID rather than an empty list. |
active_on | date | — | Point-in-time: entries on the list on this date, by our observation history. A date outside coverage_window answers screen_status: inconclusive with the window, never an empty list. |
added_since | date | — | Only entries first observed on or after this date. Ignored when active_on or removed_since is set. |
removed_since | date | — | Only entries that LEFT a list on or after this date (active: false). |
sort | enum list_entries_sort | default name | name (A–Z) or recent (latest observation first). |
limit | limit | min 1, max 100, default 25 | Maximum entries returned. |
cursor | cursor | — | Pagination cursor from pagination.next_cursor. |
offset | integer | min 0 | Legacy numeric offset; cursor is preferred. |
GET /api/v2/lists/changes
9 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
list | enum list_source_key | case-insensitive | Restrict the feed to one list, by source_key. Case-insensitive. Find keys with GET /api/v2/lists: every row with ingested: true is accepted. |
change_type | enum list_change_type | — | added, removed or changed. |
date | date | — | One snapshot date; with days it ends the trailing span on that date. |
date_start | date | — | First snapshot date of an explicit window. |
date_end | date | — | Last snapshot date of an explicit window. |
days | duration | min 1, max 30 | Trailing window in snapshot days, 1–30; 7 and 7d are both accepted. |
limit | limit | min 1, max 200, default 50 | Maximum change rows returned. |
cursor | cursor | — | Pagination cursor from pagination.next_cursor. |
offset | integer | min 0 | Legacy numeric offset; cursor is preferred. |
GET /api/v2/meta/enums
Takes no query parameters.
GET /api/v2/meta/endpoints
1 accepted parameter.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
endpoint | string | — | Return one endpoint instead of all of them. Accepts either the descriptor id (events-list) or the path (/api/v2/events). An unknown value returns 404 NOT_FOUND with the available ids in details.available. |
GET /api/v2/meta/query-units
Takes no query parameters.
GET /api/v2/search
13 accepted parameters — 6 core, 7 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
q | string | min 1, max 200 | Canonical search text: a name, alias, or acronym. Required except when browsing public officials with universe=osint and holds_office=true. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names. |
type | enum search_entity_type | — | Optional identity type used to narrow ambiguous candidates. Conflicting linked types retain entity_type=entity and type_evidence; a filtered result includes a conflict only when the requested type is a published possibility. facility searches the existing facility directory and returns facility_id, not an invented entity ID. Source entitlements apply. |
country | csv | — | Known country association from source records, not an assertion of headquarters, citizenship, or reporting location. Accepts country names, ISO-2 or ISO-3; comma-separate for OR. Use country_match=strict for candidates with known matching evidence. |
country_match | enum search_country_match | — | strict keeps only candidates with a known association to the country, region or continent you send; include_unknown also returns candidates with no country evidence. Without one of those, strict changes nothing. Omitted, it is include_unknown. |
limit | limit | min 1, max 50, default 10 | Number of records to return on this page; pagination describes how to continue. |
universe | enum search_universe | default all | Search all merged entities, news entities, reference entities, raw GLEIF registry records, or OSINT list and office-holder records. The registry and osint lanes return source records with nullable entity_id; they do not establish news coverage. Source entitlements apply. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
sort | string | — | Use name for stable alphabetical public-official browsing with universe=osint and holds_office=true. Default when q is absent. |
offset | integer | min 0 | Number of records to skip before this page. |
region | enum region | — | Geographic region whose member countries define the scope. |
continent | enum continent | — | Continent whose member countries define the geographic scope. |
include_images | boolean | — | Retain source article image URLs on returned cards when available. |
resolved_only | boolean | default false | Return only candidates linked to a canonical registry identity. Available for all, news and reference entity searches. |
holds_office | boolean | — | Only politicians: entities that hold or have held a published public office (sources.offices), or on universe=osint only office-holder records. A ROLE filter, not a type — an office-holder is a person. Requires can_use_offices (403 PLAN_REQUIRED otherwise) and is not applicable to universe=registry (legal entities only; 400). |
GET /api/v2/situations
16 accepted parameters — 10 core, 6 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
entity | string | — | Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days. |
date_start | date | — | Return Situations still running on or after this date (YYYY-MM-DD) — matched against span_end, so an occurrence that began earlier and is ongoing IS returned. Optional and independent of date_end. There is no maximum span: the Situations table is one row per adjudicated occurrence and is small by construction, so this is a filter on a stored column rather than a bound on how much is scanned. |
date_end | date | — | Return Situations that had already begun by this date (YYYY-MM-DD) — matched against span_start. Sent together with date_start the pair selects every occurrence whose span OVERLAPS the window; sent alone it leaves the other side open. An inverted pair is refused with INVALID_DATE_RANGE rather than answered empty. |
days | duration | Cannot be combined with date_start or date_end. Send days for a rolling window, or date_start/date_end for named dates. | The last N reporting days (7 or 7d), matched by span overlap like date_start/date_end. Relative, not N named dates: the window ends on the newest settled Stories date, so just after midnight UTC days=1 is yesterday. More than 30 is served as the most recent 30. meta.query_window gives the dates used and meta.window_adjustment says when they moved. When omitted (and no date_start/date_end is sent), no window applies: every current Situation is listed, and a search reads member headlines from the last 30 days. There is no equivalent numeric default: any explicit days bounds the list itself, so send it whenever the window matters. |
search | string | — | Free text matched against the stored title OR the headline of any member Story reported inside the window (the last 30 days when no dates are sent). EVERY whitespace-separated term must appear in one of the two AS A WORD, case-insensitively: a term of one or two characters as a whole word (ai finds “AI race” and never “said”), a longer term as the start of a word (nepal flood matches “Flash floods hit northern Nepal-Tibet border”), and a term in Chinese, Japanese, Thai, Lao, Khmer or Burmese script as a substring, since those scripts have no word spaces. AI slowdown finds a Situation titled “Trump says US will not slow AI race” through a member headline that says slowdown. The phrase also runs through the hybrid GET /api/v2/stories?search= in the same window, and a Situation holding one of the top-ranked Stories matches too, so AI pause can reach the same Situation through meaning; meta.search.semantic_story_candidates reports how many Story hits that arm contributed and meta.search.note says when it was unavailable. What it CANNOT do: read article text or entities directly; and title is the PEAK member’s headline, re-stamped every time the Situation is recomputed. Over 8 terms, only its content words must appear, or past 8 of those only the semantic arm matches (meta.search.long_query). To search what a Situation is actually ABOUT, run GET /api/v2/stories?search= and take any returned Story id to /api/v2/situations/{story_id}. |
sort | enum situation_sort | default recent. With sort=relevance: requires search. relevance ranks a search; without one, use recent. | Ranking. recent uses latest reporting date, then first-observed membership time; created orders by immutable creation time, newest first; updated orders by the latest serving-membership refresh; article_count, story_count and event_count are volume alternatives; span_days puts the longest-running occurrence first — the inclusive day count between span.start and span.end, with an unmeasured span last. Recent never uses refresh time or volume. relevance ranks a search: Situations whose own title holds the terms first, then by the share of member headlines in the window that hold them, then by how high GET /api/v2/stories?search= placed their best member Story, then by latest reporting. The default stays recent even with a search; send relevance to rank by the match. rising compares each Situation’s served member Stories in the last two UTC days with the seven days before: rising ranks by how far each row’s activity in the recent window rises above what its own previous 7 days predicted, scaled to the whole corpus so a part-filled day or a quiet weekend moves every row alike: (recent − expected) ÷ √(expected + 4). Rows with fewer than 3 recent records are not ranked. Each row carries a rising block with its recent, baseline and expected counts, the change multiple and both windows. Situations without a rising score follow by latest reporting. Every order breaks ties on situation_uid, so paging with offset is stable. |
limit | limit | min 1, max 200, default 25 | Number of Situations returned on this page. pagination.total is the true number matching your filters, counted separately from the page, so has_more is measured rather than inferred from a full page. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
country | enum country | — | Any member-linked coded Event located in this ISO-3 country. Actor nationality is not used. Requires date_start and date_end, at most 30 inclusive days. Both country and category match the SAME Event. |
category | enum event_category | — | Any member-linked coded Event in this Event taxonomy category, not Story category or a primary Situation label. Requires both reporting date bounds, at most 30 days. Country and category match the same Event. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
story_id | string | — | Stored Situation UID from search_situations, or a member Story ID when supported by this operation; reuse the returned identifier. |
event_uid | string | — | Coded Event UID from search_events; selects Situations with member Stories linked to that Event. |
include_map | boolean | default false | Include country aggregates over every matching Situation, independently of page size. Requires a reporting window of at most 30 days. |
min_stories | integer | min 0, max 4294967295 | Minimum member Stories across the whole current servable membership, not the selected reporting window. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds. This filter does not change creation, growth or direct UID lookup. |
min_articles | integer | min 0, max 4294967295 | Minimum articles across the member Stories — the best single proxy for how big an occurrence got, and the default sort key. Compared against the stored article_count. |
min_events | integer | min 0, max 4294967295 | Minimum coded Events at canonical-incident grain across the whole current servable membership. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds, including reporting with no coded Events. Explicit zero is permitted. |
GET /api/v2/situations/{story_id}
9 accepted parameters — 2 core, 7 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 200, default 50 | Number of records to return on this page; pagination describes how to continue. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
edition_id | string | Cannot be combined with as_of. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Retained edition identifier from get_situation_editions. Pins the published snapshot. |
as_of | instant | Cannot be combined with edition_id. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. |
date_start | date | — | Earliest member date to include. Defaults to seven days before the anchor Story’s own date — not to today, because a situation is anchored on a Story, not on the request clock. On a curated Situation it filters the stored membership and coverage is re-derived from the members that survived, so the window reported is never wider than the payload. |
date_end | date | — | Latest member date to include. Defaults to seven days after the anchor Story’s own date. The span may not exceed 30 days when both bounds are sent — the same ceiling the service compares against, not a number typed into a sentence. On a curated Situation, sending neither bound returns the whole stored span; sending one leaves the other side open. |
depth | integer | min 1, max 3, default 1 | Number of adjudicated connection hops from the anchor in a walked Situation. Indirect reachability is not direct comparison with the anchor. Curated membership ignores this value and discloses that in applied_filters. |
max_nodes | integer | min 1, max 250, default 250 | Member Story cap for the Situation graph, independent of page size. Read truncated and caps.members; the limit can bound membership totals. |
include | enum situation_include | — | Optional blocks. edges returns one undirected row per adjudicated pair across the bounded graph membership, independently of Story pagination (limit and offset). An edge can reference a Story outside the returned page; fetch the member pages to hydrate those IDs and inspect caps and scopes for coverage. /connections pages membership provenance, not pairwise edges. Edges are omitted by default; totals.edge_count reports all pairs in the selected scope even when the returned graph is capped. |
GET /api/v2/situations/{story_id}/entities
8 accepted parameters — 3 core, 5 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
entity_type | string | — | Case-insensitive entity kind from summary.by_type. unknown selects untyped records; filtering happens after identity folding. |
limit | limit | min 1, max 200, default 25 | Number of records to return on this page; pagination describes how to continue. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
edition_id | string | Cannot be combined with as_of. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Retained edition identifier from get_situation_editions. Pins the published snapshot. |
as_of | instant | Cannot be combined with edition_id. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. |
scope_version | string | — | Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. |
date_start | date | — | Optional earliest member reporting date. Omit both dates for the full servable membership. |
date_end | date | — | Optional latest member reporting date. No implicit first200-member truncation. |
GET /api/v2/situations/{story_id}/stories
8 accepted parameters — 2 core, 6 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; pagination describes how to continue. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
edition_id | string | Cannot be combined with as_of. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Retained edition identifier from get_situation_editions. Pins the published snapshot. |
as_of | instant | Cannot be combined with edition_id. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. |
scope_version | string | — | Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. |
date_start | date | — | Optional earliest member reporting date. Omit both dates for the full servable membership. |
date_end | date | — | Optional latest member reporting date. No implicit first200-member truncation. |
record_ids | string | Requires one of edition_id or as_of. The selected records stay frozen only inside one retained edition. Cannot be combined with date_start or date_end. | Up to eight comma-separated retained Story IDs. Returns complete frozen records in edition order. Offset and limit paginate that selected set. |
GET /api/v2/situations/{story_id}/events
8 accepted parameters — 2 core, 6 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; pagination describes how to continue. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
edition_id | string | Cannot be combined with as_of. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Retained edition identifier from get_situation_editions. Pins the published snapshot. |
as_of | instant | Cannot be combined with edition_id. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. |
scope_version | string | — | Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. |
date_start | date | — | Optional earliest member reporting date. Omit both dates for the full servable membership. |
date_end | date | — | Optional latest member reporting date. No implicit first200-member truncation. |
record_ids | string | Requires one of edition_id or as_of. The selected records stay frozen only inside one retained edition. Cannot be combined with date_start or date_end. | Up to eight comma-separated retained Event UIDs. Returns complete frozen records in edition order. Offset and limit paginate that selected set. |
GET /api/v2/situations/{story_id}/connections
7 accepted parameters — 2 core, 5 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; pagination describes how to continue. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
edition_id | string | Cannot be combined with as_of. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Retained edition identifier from get_situation_editions. Pins the published snapshot. |
as_of | instant | Cannot be combined with edition_id. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. |
scope_version | string | — | Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. |
date_start | date | — | Optional earliest member reporting date. Omit both dates for the full servable membership. |
date_end | date | — | Optional latest member reporting date. No implicit first200-member truncation. |
POST /api/v2/situations
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
GET /api/v2/situations/{story_id}/brief
3 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
edition_id | string | Cannot be combined with as_of. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Retained edition identifier from get_situation_editions. Pins the published snapshot. |
as_of | instant | Cannot be combined with edition_id. Select one edition. Requires the {story_id} path segment to match ^sit_[A-Za-z0-9_-]{1,124}$. Retained editions exist only for a stored Situation UID. | Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began. |
level | string | — | Progressive detail level: brief (default), structure, context. |
GET /api/v2/situations/{story_id}/editions
2 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; pagination describes how to continue. |
offset | integer | min 0, default 0 | Number of records to skip before this page. |
GET /api/v2/entities
24 accepted parameters — 11 core, 13 advanced.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | EVENT TIME — inclusive start of the window by when it HAPPENED (YYYY-MM-DD). Windows are capped at 30 inclusive days. Use consecutive date chunks; calendar months can exceed the cap. Follow the endpoint’s pagination guidance within each chunk. |
date_end | date | — | EVENT TIME — inclusive end of the window by when it HAPPENED (YYYY-MM-DD). |
days | duration | — | Calendar-date window ending today, in days (max 30). When omitted, entity coverage uses the last 30 calendar days with an observed-time bound over the same span. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass days explicitly, or date_start/date_end, whenever the window matters. |
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
co_occurring_with | enum entity_handle | — | Return the entities that appear ALONGSIDE this one — the entities linked to the same Stories, over the same window, narrowed by every other filter on this endpoint. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the same arbiter as entity= on /api/v2/events and /api/v2/stories, so one handle means the same entity everywhere. The subject is never returned in its own results. Co-occurrence is measured over SHARED STORIES — appearing in the same coverage, which is not a claim that the two entities interacted. A handle that resolves to nothing returns an EMPTY list with a linkage reason in applied_filters, never the global top entities. |
country | csv | case-insensitive | Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event’s own location OR either actor’s origin country by default, so a result can include events that happened elsewhere — set country_match to narrow it to location only. The definition in force is echoed as applied_filters.country_match. |
type | enum entity_type | — | Restrict to one or more comma-separated entity types. |
q | string | — | Entity NAME to resolve. Matched across every entity universe and ranked by match quality (exact name, exact alias, acronym, prefix, fuzzy) before coverage — see each row’s match_type and match_reason. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names. |
story_search | string | Cannot be combined with q. Use q to resolve an entity by name, story_search for a topic. | A TOPIC, not a name: list the people and organizations in the Stories that match this text. Runs the same search as /api/v2/stories?search= with this request’s window, place, taxonomy, language and fatality filters (and co_occurring_with as the Stories entity=), reads its first 100 Stories, and ranks each entity by the Stories that carry it, each weighted by how closely it matches ((search_score / best)^4; sort=recent: by the latest such Story). Each row’s story_search_match holds the count, articles, that relevance sum and up to three Story ids; metrics are not measured by this read and are null. meta.story_search.stories_request is the exact Stories call the counts come from. |
sort | enum entity_sort | default significance. With sort=rising: cannot be combined with q, story_search, target_type, target_ids, nearby_radius_km, co_occurring_with, country, region, continent, category, subcategory, languages, has_fatalities or civilian_targeting. Send rising with type and a window only; narrow the subjects with sort=significance. | recent orders an unfiltered directory by latest Story reporting time (latest_observed_news_at), then Story and article volume within the same timestamp. Filtered and q requests retain candidate news-date precision (latest_observed_news_date) because those predicates are not all materialized on serving Stories. Registry or link-processing times never lead. With significance, q resolves by match quality first; resolved counts and latest_date do not reorder the fixed candidate page. With rising, the requested window is the recent window and Stories are counted on serving Stories. rising ranks by how far each row’s activity in the recent window rises above what its own previous 7 days predicted, scaled to the whole corpus so a part-filled day or a quiet weekend moves every row alike: (recent − expected) ÷ √(expected + 4). Rows with fewer than 3 recent records are not ranked. Each row carries a rising block with its recent, baseline and expected counts, the change multiple and both windows. Rising ranks the unfiltered directory (type and the window only). |
| Parameter | Type | Constraints | Description |
|---|---|---|---|
region | enum region | — | Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules. |
continent | enum continent | — | Continent expanded to its member ISO-3 countries; applied through the same country matching rules. |
country_match | enum country_match | default location_or_actor_origin | Which definition of “in this country” the country / region / continent filters use. Applies to region and continent too, since both expand into the same country set. Note that group_by=country buckets on the event’s own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass country_match=location when you need the two to agree. |
category | enum event_category | case-insensitive | Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with subcategory: an impossible pair returns 400, never an empty 200. |
subcategory | csv | — | Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by category — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (Sexual violence is the measured example: its definition boundary sends nearly all such reporting to Attack). Before building a monitor on one code, measure it: GET /api/v2/events/summary?group_by=subcategory returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. |
target_type | enum target_type | Requires target_ids. With target_type=facility: requires related_scope=connected unless nearby_radius_km is sent. A facility has no news identity of its own: send nearby_radius_km for the people and organizations in the Stories near it, or related_scope=connected for those in its identified owners’ Stories. Cannot be combined with q or co_occurring_with. A Stories scope lists the entities in those Stories; q resolves a name. | Typed selected root for a shared connected scope: entity or facility. Lists the people and organizations in the Stories of this scope, as /api/v2/stories reads it (see story_search). |
target_ids | csv | Requires target_type. Cannot be combined with q or co_occurring_with. A Stories scope lists the entities in those Stories; q resolves a name. | Comma-separated stable IDs of the target_type kind (up to 25); roots are unioned. Lists the people and organizations in the Stories of this scope, as /api/v2/stories reads it (see story_search). |
related_scope | enum related_scope | default direct. Requires target_type and target_ids. Cannot be combined with q or co_occurring_with. A Stories scope lists the entities in those Stories; q resolves a name. | direct matches the selected targets only. connected also matches, for an entity, the companies it owns or consolidates: subsidiaries its SEC Exhibit 21 lists and its GLEIF consolidated children, direct or naming it as ultimate parent, down five levels and up to 250 companies per target. Only companies that are themselves registry entities are added, and an entity target expands only from its e_… registry id. For a facility, connected adds its identified owners and their parent companies. applied_filters.relationship_paths lists each added company and the relationship that added it; applied_filters.target_scope_complete is false, with reasons in target_scope_gaps, when the expansion stopped short. Lists the people and organizations in the Stories of this scope, as /api/v2/stories reads it (see story_search). |
nearby_radius_km | number | min 1, max 250. Requires target_type=facility. | With target_type=facility and related_scope=direct: the people and organizations in the Stories behind the Events within this many km of the facility (the same scope as /api/v2/stories). Proximity is not participation. |
languages | enum coverage_language | — | ISO source-language filter. Restricts coverage metrics to articles in those languages. |
has_fatalities | boolean | — | Restrict to entities linked to fatal events. |
civilian_targeting | boolean | — | Restrict to entities linked to events coded as civilian targeting. |
include_images | boolean | — | Attach Wikipedia thumbnail/avatar URLs where available. Off unless requested — the images cost an extra lookup. |
GET /api/v2/entities/{entity_id}/dossier
2 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
as_of | date | — | Date-filtered dossier: ingredients are filtered to facts dated on or before this date; offices use the office start/end dates the source publishes. Identity and attribution still use current knowledge, so meta.no_lookahead remains false. Absent = current knowledge. A past date needs can_use_asof. |
event_days | integer | min 1, max 30, default 30 | Trailing calendar window including the end date, in days. summary.events_in_window and summary.stories_in_window count coded occurrences and coverage Stories separately using the public serving summaries; the Event timeline preview is. |
GET /api/v2/entities/{entity_id}/interactions
5 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
date_start | date | — | Inclusive first Event date (YYYY-MM-DD). With date_end, a literal window of at most 30 days. |
date_end | date | — | Inclusive last Event date (YYYY-MM-DD). |
days | duration | min 1, max 30, default 30 | Calendar-day window ending today (max 30). A window whose last day is not yet served slides to the newest served day; meta.window_adjustment says so. |
limit | limit | min 1, max 50, default 10 | Counterparts to return in EACH direction (acts_on, acted_on_by). Default 10, max 50. |
resolved_only | boolean | default false | Drop counterparts the coder named without an entity id (roles such as “investors”). Default false. |
GET /api/v2/offices
11 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
include_facets | boolean | default false | Include complete country facets over the served office registry, independent of pagination and country/name filters. Holder counts are terms across offices, not distinct people. Null facets mean unavailable. |
country | enum country | case-insensitive | Country of the office (ISO-3, ISO-2, or a name; comma-separate for OR). IGO / supranational posts carry no country and never match a country filter — use scope=international for those. |
scope | enum office_scope | case-insensitive | Level of government: national, subnational (state / province / municipality) or international (IGO and supranational posts). Derived from the source’s topics; an office with no scope topic is national. |
branch | enum office_branch | case-insensitive | Branch of government. head (head of state / government) wins over executive when a office carries both topics. other is sendable and returns the offices whose topics name no recognised branch. |
organization | string | — | The legislature / ministry / court the office belongs to. A spine e_… id matches the resolved organization exactly (the arbiter family, so a merged-away alias still matches); any other value is a case-insensitive substring match on the organization name as published. |
q | string | — | Case-insensitive substring match over the office name. This is NOT semantic search — nothing is embedded, and a conceptually related term that does not appear literally will not match. Results keep the sort order, not a relevance ranking, so a query matching more rows than limit returns the first page of that order — narrow with country. |
has_holders | boolean | — | true restricts to offices with at least one office-holder on record (any status); false to offices we know only as an office, with nobody recorded in it. This counts office_holders, not asserted currency — an office whose only holders are status: unknown still has holders. |
as_of | date | — | VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the can_use_asof gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — meta.undated_office_holders counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”. |
sort | enum offices_sort | default name, case-insensitive | Ordering: name (default) · holders_desc · country. |
GET /api/v2/offices/{office_id}
1 accepted parameter.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
as_of | date | — | VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the can_use_asof gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — meta.undated_office_holders counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”. |
GET /api/v2/offices/{office_id}/holders
4 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 200, default 50 | Number of records to return on this page; use the returned continuation to request the next page. |
cursor | cursor | — | Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. |
status | enum office_holder_status | case-insensitive | Restrict to office-holders the PUBLISHER asserts as current, ended or unknown. unknown is a real bucket, not a synonym for current: the source did not say, and nothing here infers currency from a missing end_date. Combine with as_of to ask “current AND in office on that date” — the two are independent predicates. |
as_of | date | — | VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the can_use_asof gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — meta.undated_office_holders counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”. |
GET /api/v2/entities/{entity_id}/offices
3 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
status | enum office_holder_status | case-insensitive | Restrict to office-holders the PUBLISHER asserts as current, ended or unknown. unknown is a real bucket, not a synonym for current: the source did not say, and nothing here infers currency from a missing end_date. Combine with as_of to ask “current AND in office on that date” — the two are independent predicates. |
as_of | date | — | VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the can_use_asof gate and does not answer “what did we know then”. An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — meta.undated_office_holders counts how many the date could not see. A future date is accepted and reads as “still in office as far as the source has published”. |
limit | limit | min 1, max 200, default 100 | Maximum office-holders to return. Default 100, max 200; truncated: true when the entity has more. |
GET /api/v2/geo/admin1
5 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
country | string | required | Country to enumerate admin1 (state/province) values for — required. Accepts a country name (France), ISO-2 (FR), or ISO-3 (FRA); an unresolvable or missing value returns 400 INVALID_COUNTRY. |
days | duration | min 1, max 30, default 30 | Trailing window in days the region counts are measured over, ending today unless date moves the anchor. Both 7 and 7d are accepted. The window actually used is echoed as window_days and in applied_filters. |
date | date | — | Anchor date for the window. Alone it selects that single day; combined with days it ends the trailing span on that date. |
date_start | date | — | First day of an explicit window. May not be combined with days/window. |
date_end | date | — | Last day of an explicit window. May not be combined with days/window. |
GET /api/v2/monitors
Takes no query parameters.
POST /api/v2/monitors
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
GET /api/v2/monitors/{id}
Takes no query parameters.
PATCH /api/v2/monitors/{id}
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
DELETE /api/v2/monitors/{id}
Takes no query parameters.
POST /api/v2/monitors/preview
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
POST /api/v2/monitors/demo-webhook
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
POST /api/v2/monitors/batch
Takes no query parameters. See the linked operation schema in the API reference for its JSON request body.
GET /api/v2/monitors/{id}/runs
3 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
view | enum monitor-run-view | default full | summary returns each run without results, matched_items and evaluation_json; page its records with the matches endpoint. full (today’s default) returns them, and is deprecated: summary becomes the default on or after 2026-12-03 (see the API stability page). Build on summary. |
limit | limit | min 1, max 100, default 25 | Runs per page. Default 25, max 100. A value outside the range is refused, not clamped. |
offset | integer | min 0, max 100000, default 0 | Rows to skip, for paging back through the seven-day retention window. Plain integer offset — this endpoint has no opaque cursor. |
GET /api/v2/monitors/{id}/runs/{runId}
1 accepted parameter.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
view | enum monitor-run-view | default full | summary returns each run without results, matched_items and evaluation_json; page its records with the matches endpoint. full (today’s default) returns them, and is deprecated: summary becomes the default on or after 2026-12-03 (see the API stability page). Build on summary. |
GET /api/v2/monitors/{id}/runs/{runId}/matches
2 accepted parameters.
| Parameter | Type | Constraints | Description |
|---|---|---|---|
limit | limit | min 1, max 100, default 25 | Matched items per page. Default 25, max 100. A value outside the range is refused, not clamped. |
cursor | cursor | — | Opaque cursor over the run’s frozen matched-item list. Copy next_cursor from the previous response verbatim; omit it for the first page, and stop when it is null. It is not an offset — a plain integer is refused rather than answered with page one. |
GET /api/v2/monitors/{id}/runs/{runId}/matches.csv
Takes no query parameters.
POST /api/v2/monitors/{id}/run-now
Takes no query parameters.
POST /api/v2/monitors/{id}/test-delivery
Takes no query parameters.
GET /api/v2/energy/assets/{tracker}/{gem_id}
Its parameters are listed on its API reference page.
GET /api/v2/energy/assets
Its parameters are listed on its API reference page.
GET /api/v2/energy/assets/summary
Its parameters are listed on its API reference page.
GET /api/v2/energy/owners/{entity_id}
Its parameters are listed on its API reference page.
GET /api/v2/energy/owners
Its parameters are listed on its API reference page.
GET /api/v2/entities/{entity_id}/hierarchy
Its parameters are listed on its API reference page.
GET /api/v2/entities/{entity_id}
Its parameters are listed on its API reference page.
GET /api/v2/entity-tone
Its parameters are listed on its API reference page.
GET /api/v2/events/{event_id}
Its parameters are listed on its API reference page.
GET /api/v2/events/{event_id}/stories
Its parameters are listed on its API reference page.
GET /api/v2/filings/{cik}/facts
Its parameters are listed on its API reference page.
GET /api/v2/filings/{cik}/relations
Its parameters are listed on its API reference page.
GET /api/v2/filings/{cik}
Its parameters are listed on its API reference page.
GET /api/v2/filings/events
Its parameters are listed on its API reference page.
GET /api/v2/filings
Its parameters are listed on its API reference page.
GET /api/v2/filings/summary
Its parameters are listed on its API reference page.
GET /api/v2/gleif/entities/{lei}
Its parameters are listed on its API reference page.
GET /api/v2/gleif/entities
Its parameters are listed on its API reference page.
GET /api/v2/gleif/isin
Its parameters are listed on its API reference page.
GET /api/v2/gleif/relationships
Its parameters are listed on its API reference page.
GET /api/v2/gov/awards
Its parameters are listed on its API reference page.
GET /api/v2/gov/fara
Its parameters are listed on its API reference page.
GET /api/v2/macro/observations
Its parameters are listed on its API reference page.
GET /api/v2/macro/releases
Its parameters are listed on its API reference page.
GET /api/v2/macro/series/{series_id}
Its parameters are listed on its API reference page.
GET /api/v2/macro/series
Its parameters are listed on its API reference page.
GET /api/v2/maritime/chokepoint-watch
Its parameters are listed on its API reference page.
GET /api/v2/maritime/dwell
Its parameters are listed on its API reference page.
GET /api/v2/maritime/gaps
Its parameters are listed on its API reference page.
GET /api/v2/maritime/port-pulse
Its parameters are listed on its API reference page.
GET /api/v2/maritime/ports
Its parameters are listed on its API reference page.
GET /api/v2/maritime/transits
Its parameters are listed on its API reference page.
GET /api/v2/maritime/vessels
Its parameters are listed on its API reference page.
GET /api/v2/stories/{story_id}
Its parameters are listed on its API reference page.
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. |
entity
On 18 endpoints.
| Endpoint | What this endpoint says it accepts |
|---|---|
/api/v2/activity | Selected entity ID from /api/v2/search; returns records linked to that identity. |
/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/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/entity-tone | The entity to measure: an id (e_… or wiki:…) or a name, which resolves to one canonical entity. |
/api/v2/events | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle |
/api/v2/events/summary | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle |
/api/v2/exposure | Resolved entity identifier. |
/api/v2/facilities | The owner: an entity id, or a name resolved to one entity through the shared entity resolver. Use owner_search to match owner names loosely instead. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle |
/api/v2/filings | Restrict to one entity’s SEC filings. Takes the SAME entity identifier as the other per-entity surfaces — a spine e_… id, a news wiki:…/llm:… id, or a merged alias of either — resolved through the shared resolver, so the id you used on /api/v2/events or /api/v2/gov/awards selects the same company here. Resolution maps the entity to its SEC Central Index Key(s); the applied set is echoed as applied_filters.entity_cik, and an entity carrying two filer numbers matches BOTH. An entity-scoped read is a primary-key seek, so it is NOT capped at 30 days (it defaults to the last year, like cik). A known entity with no SEC filer identity returns an empty result with a note — never the unfiltered feed — and an identifier that resolves to no known entity is refused with 400 UNRESOLVED_ENTITY_ID rather than silently ignored. Combine with cik to intersect the two. Resolve a NAME first with GET /api/v2/search or GET /api/v2/filings/resolve?q=<name>. |
/api/v2/filings/events | Restrict to 8-K events that name this entity as the filer or a counterparty: an e_… id or a wiki:… news id, resolved to one canonical entity. Resolve a name first with GET /api/v2/search. |
/api/v2/filings/relations | The named company: a registry e_ id, or a news wiki:/llm: id bridged to the registry. Rows stored under any id that has since merged into it are included. A bare name is refused (INVALID_ENTITY_ID); resolve it first with /api/v2/filings/resolve?q= (its entity_id) or /api/v2/entities?q=. |
/api/v2/gov/awards | A resolved spine entity id (e_… / wiki:… / cik:…). A bare name is rejected with 400 INVALID_ENTITY_ID — resolve it first via GET /api/v2/search. Returns that entity’s federal awards. |
/api/v2/gov/fara | A resolved spine entity id (e_…). Matches the registrant OR the foreign principal side of the link. |
/api/v2/lists/entries | Only entries resolved to this entity — an e_ spine id or a wiki: news id, collapsed through the arbiter. An id the registry has never heard of answers 400 UNRESOLVED_ENTITY_ID rather than an empty list. |
/api/v2/share-of-voice | Entities to measure, as ids (e_…, wiki:…) or names, comma-separated. Each one resolves to a canonical entity; resolved_entities and unresolved_terms show how. |
/api/v2/situations | Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days. |
/api/v2/stories | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle |
/api/v2/stories/summary | Restrict to an entity’s resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. A spine id naming a retired row (a dataset cell that names several organisations, or an aggregate label) is refused with 400 ENTITY_RETIRED, whose details.members lists the entities it names. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. 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}/dossier | The entity id. |
/api/v2/entities/{entity_id}/hierarchy | A name, an e_ spine id, a wiki: news id, a wikipedia_url, or a bare 20-character LEI. |
/api/v2/entities/{entity_id}/interactions | The entity id. |
/api/v2/entities/{entity_id}/offices | The entity id. |
entity_search
On 1 endpoint.
| Endpoint | What this endpoint says it accepts |
|---|---|
/api/v2/exposure | Fuzzy entity resolver query. |
facility_id
On 4 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}/observations | The facility id. |
/api/v2/facilities/{facility_id}/relationships | 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. |
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 3 endpoints.
| Endpoint | What this endpoint says it accepts |
|---|---|
/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/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 2 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/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/summary | Legacy — prefer the canonical entity param (still fully supported). Case-insensitive substring match against the raw owner string. |
/api/v2/facilities | Owner name to match loosely, including names that resolve to no entity. Use entity for one resolved owner. |
ticker
On 1 endpoint.
| Endpoint | What this endpoint says it accepts |
|---|---|
/api/v2/filings/resolve | Exact ticker symbol. |
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.
