Find your data.
Choose your endpoint.

Paginated observed evidence of successful serving/reference publication. Unchanged reloads and baseline inventories are excluded. Linked entities are mentions or participants according to the record; they are not newly created identities. Source dates retain their stated precision. Source capability and collection start are explicit; missing history is not zero. Reads are ordered by the selected time_basis, newest first. Only committed batches are visible; cursors pin committed source sequences across pages. recorded_at retains journal availability time independently from published_at and source_date. Exhausting next_cursor completes the observed journal at its publication cutoff, not all upstream source intake. Query Monitors may watch observed publication entries while retaining source/history qualifications; partial history cannot establish exhaustive all-source counts or quiet days. Failed, unavailable or capped journal reads cannot complete a Monitor checkpoint.

Response: PublicationActivityCard · MCP tool: get_activity

Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. Finish pagination.next_cursor within each fixed window before starting the next chunk without a cursor. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Discrete events we code in-house from news coverage into a CAMEO+ / ACLED-aligned taxonomy. Each carries: the ACTORS on both sides (actors, with their countries and roles), geography down to admin-1 with a stated precision, the linked story and its source articles, a written rationale, and a set of METRICS — significance (the default sort, and the only one meant to compare events across domains), plus magnitude, systemic_importance, propagation_potential and market_sensitivity, each filterable with <metric>_min / <metric>_max. Goldstein and quad class are published where the taxonomy defines them. Metric values also carry metrics.metric_inputs: the sub-factor scores the coder read off the article, each with the reason it gave — so a score can be audited rather than trusted. Definitions: https://docs.gdeltcloud.com/reference/metrics

Response: EventCard · MCP tool: search_events

Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. Finish pagination.next_cursor within each fixed window before starting the next chunk without a cursor. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Deduplicated news Stories — clusters of articles about the same real-world development, built by us from the articles themselves. Each carries the source articles behind it, article and outlet counts, the coverage languages it appeared in, the entities it mentions, and the Events coded from it. One story can yield several events. related=true attaches adjacent clusters; Stories independently adjudicated as the same incident always share one canonical public representative. matched_categories reports which of your taxonomy filters each story actually matched, which is the fastest way to see why a result came back. Stories do not accept Event metric filters such as significance_min; query /api/v2/events with the metric filter and follow each Event's story_refs instead.

Response: StoryCard · MCP tool: search_stories

Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Aggregate counts and metric statistics over the same Events /api/v2/events returns, grouped by date, country, region, continent, category or subcategory. Accepts every filter the list accepts, so a summary and a list of the same window are directly reconcilable. Metric averages are means over the rows where that metric is present, not over event_count — family-scoped metrics are genuinely absent on the other family.

Response: EventSummaryBucket · MCP tool: summarize_events

Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Aggregate counts and statistics over the same Stories /api/v2/stories returns, grouped by date, country, region, continent, category or subcategory. Event-scoped filters are applied inside the linked-event rollup, so a story's counts reflect the events that matched your filters rather than its total. With group_by=country, country_attribution=all counts each distinct Story under every country matching the ordinary Stories country filter. Country buckets may overlap; use group_by=date for distinct global totals.

Response: StorySummaryBucket · MCP tool: summarize_stories

Compare an entity’s share of canonical settled Story records within one explicit news denominator. Story membership and entity references come from the Core serving tables; unsupported article-level and upstream-salience weighting are not published.

Response: ShareOfVoiceResponse · MCP tool: share_of_voice

Canonical-URL-deduplicated article evidence with source language and provenance-backed publisher country.

Response: Structured JSON response · MCP tool: get_story_articles

Discover stored Situations by title, current servable span overlap and volume counts, or member-linked coded Event location/category. Event facets require a reporting window of at most 30 days and match the same Event; they do not establish a primary country or category. Directory filtering, ordering and totals use current full serving membership. scope and selected_scope distinguish whole-Situation counts from requested reporting dates and carry content versions. narrative is a dated, independently verified summary when one has been published; null means unavailable. Entity counts cover all current servable members and are null if measurement fails.

Response: SituationSummaryCard · MCP tool: search_situations

Every Story and Event belonging to one real-world occurrence. The path accepts EITHER a situation_uid (sit_…) or any member Story id, and both return the same occurrence — a Story resolves to its primary Situation. A situation_uid is minted and content-independent, so it never changes; a Situation that merges into another resolves FORWARD to the survivor rather than 404ing. meta.situation_source says which you got: curated is the stored, adjudicated membership set, and walked is the adjudicated neighbourhood around a Story that no Situation covers yet — the same shape, a weaker claim. Stored members carry route; antecedent and consequence are chronological, not proof of causality. membership reports the basis and any recorded decision reason; missing evidence stays null. origin is the earliest member carrying material coverage and peak the largest; both are derived and recomputed, and neither is the identity. Membership is not exclusive — a Story may belong to more than one Situation. Returns the member Stories (paged, with the relation and the evidence arm that produced each link), a per-day rollup of how the occurrence built up, and its Events collapsed to one row per canonical incident. How Stories adjudicated as the SAME incident are reported DIFFERS BY PATH, so read meta.situation_source first. On a walked situation they are folded out of the member list and listed under duplicates; on a curated one they are admitted as MEMBERS carrying route same_incident, duplicates is empty by construction, and how many there are is totals.story_count minus totals.distinct_incident_count. Either way, if the Story you asked for was the folded side, the situation is served from its survivor and requested_story_id names what you sent. Members and Events resolve through the same settled tables /api/v2/stories and /api/v2/events read, so a situation can never name a record those endpoints will not return. incident_relations publishes only independently adjudicated, directional umbrella/component links; it never changes Event identity or event_count, and null confirmed counts mean relation publication is unavailable or incomplete for the returned Event dates rather than zero. The Situation graph hides confirmed umbrella summaries by default and lets the reader reveal both summaries and containment edges. Curated responses include scopes.whole and scopes.selected, each with a content version and full totals independent of graph limits. narrative, when present, is independently verified and dated; current=false retains a previous publication while a refresh is pending. The incident_adjudication split describes returned incident rows, not unseen Events. Fatalities are reported as both a maximum and a raw sum, and the incident count ships with its adjudication split, because most Events have never been compared to anything. Three arrays are bounded — member Stories, incidents and the entity cast — and caps reports each ceiling and whether it bit, so nothing here is capped in silence.

Response: SituationCard · MCP tool: get_situation

Paginated canonical entities across full servable stored membership, independently of the detail endpoint’s 40-entity or 200/250-member view. Identity merging precedes type filtering and pagination. summary.entity_count and by_type cover the whole requested scope; pagination.total covers the type filter. Bounded query failure returns an error, never a partial exact total. Shared auth and query quotas apply.

Response: SituationEntityCard · MCP tool: get_situation_entities

Independently paginated stories over current servable membership. Summary and pagination totals cover all matching members, never a graph sample. Article counts sum member Story counts, not unique URLs. Date filters select member reporting dates; Event occurrence dates remain separate.

Response: SituationMemberStoryCard · MCP tool: get_situation_stories

Independently paginated events over current servable membership. Summary and pagination totals cover all matching members, never a graph sample. Article counts sum member Story counts, not unique URLs. Date filters select member reporting dates; Event occurrence dates remain separate. Event facts are hydrated from serving_events, while serving_event_story_links supplies membership only. incident_relations contains accepted directional umbrella/component links whose two endpoints are on this returned page; nullable summary counts distinguish unavailable or incomplete publication from a measured zero.

Response: SituationMemberEventCard · MCP tool: get_situation_events

Every servable membership connection, independently paginated and grouped by reporting day. Includes the stored membership relationship, first-observed timestamp, linking Story and recorded adjudication evidence. This is membership provenance, not a causal assertion or a sampled pair graph.

Response: SituationConnectionCard · MCP tool: get_situation_connections

Edition-bound as-of explanation, salient Events and actors, supported relationships, time-step traversal, full-scope statistics, frozen citations, previews and detail links. New editions do not forecast. Structure adds typed graph nodes and edges; context adds source-gated existing context. No model calls occur during reads. Unavailable analysis remains explicit.

Response: SituationBrief · MCP tool: get_situation_brief

Immutable manifests newest first, including stable daily references. Capture time, reporting cutoff and publication time are distinct. Retention begins at rollout; older clipped snapshots are not reconstructed.

Response: SituationEdition · MCP tool: get_situation_editions

Media tone toward a specific entity over a date window, with optional cited evidence. Requires a plan with Entity media tone access (can_use_tone) — see Pricing for the plans that include it. **bucket is not a parameter of this endpoint.** Entity tone is always DAILY. The series is scored per entity per story per day and the response carries bucket_granularity: "day" on every row; there is no weekly or monthly aggregation to request. The spec previously advertised bucket=day|week|month, which the service never parsed — bucket=month returned daily rows with a 200. Aggregate on your side, or narrow the window with date_start/date_end. **quality is not a parameter of this endpoint.** Not applied. Entity tone rows are served as scored; there is no quality tier to select. Filter on the score_status and confidence fields carried on each row instead.

Response: status, start_date, end_date, entities, resolved_entities, unresolved_terms, entity_coverage, rows, methodology, evidence_samples, language_breakdown

Entity-conditioned media tone, risk, and confidence over a window, with cited evidence. Resolve the entity first with /api/v2/search. Requires a plan with Entity media tone access (can_use_tone) — see Pricing for the plans that include it.

Response: status, start_date, end_date, entities, resolved_entities, unresolved_terms, entity_coverage, rows, methodology, evidence_samples, language_breakdown

Status + result of a queued entity-tone run. Requires a plan with Entity media tone access (can_use_tone) — see Pricing for the plans that include it.

Response: success, data

List entity-tone scoring runs. Requires a plan with Entity media tone access (can_use_tone) — see Pricing for the plans that include it.

Response: success, data, pagination

Fetch one known structured Event by ID.

Response: success, data

Stored, addressable Stories connected to this Event through primary or rehomed links. Incident-member IDs resolve to the canonical Event. Published serving edges select membership; Story titles, dates and article counts come from the published Story snapshot. The serving edge does not yet project relationship roles, so bounded live provenance supplies primary/rehomed roles only within published membership. Metadata declares mixed relationship provenance and partial coverage; this context is not a whole-Event Story total. Default bounds anchor to the Event date; supplied/default bounds include two additional days on either side. Returns up to 50 Stories ordered by article count descending. meta.pagination reports limit, returned, has_more and total:null; has_more indicates additional matching context beyond the returned cap. A Story excluded only by general-list dedup remains addressable here. relation is reconnected for rehomed-only links, otherwise primary (primary takes precedence). An unavailable Story or serving-edge snapshot returns retryable 503; missing stored membership or Stories are not reconstructed from the warehouse.

Response: success, data, meta

Fetch one known Story by ID with linked Events, linked Entities, metrics, public URL, normalized geo, and top 3 inline articles.

Response: success, data

Resolve a name, alias, or acronym into ranked entity candidates before creating a Monitor or calling an entity-conditioned endpoint. q is the canonical query parameter; choose a result and reuse its entity_id for reporting. Facility candidates retain facility_id for facility context; ownership and proximity are distinct from identity. The registry and osint universes instead return source records; a null entity_id means that record has no spine link and does not establish news coverage. Native non-Latin-script matching is not yet complete: for Cyrillic, Chinese and other non-Latin names, use a common Romanized or English spelling for now (for example Gazprom rather than Газпром, or Beijing rather than 北京). Native-script queries outside supported scripts return an explicit error. Candidate source failures return retryable ENTITY_SEARCH_UNAVAILABLE; a failed read never establishes the absence of a match.

Response: success, query, count, pagination, data, applied_filters, meta · MCP tool: unified_entity_search

Discover people, organizations and places appearing in reporting. For initial identity lookup, use /api/v2/search?q=…, select a candidate, then reuse its ID on the destination endpoint. This endpoint returns coverage metrics over the requested window. search= resolves a NAME across every entity universe we hold — news, the GDELT Cloud spine (SEC/EDGAR, GLEIF, GEM), sanctions lists, China-Abroad and Epoch — and each row reports the same entity_id join key as /api/v2/search (with legacy id retained), plus match_type / match_reason / match_score so the ranking can be audited rather than trusted. Metrics are the entity's resolved-layer coverage IN THE WINDOW, so a searched company with a successful empty coverage read reports zeros. Failed count reads report null with coverage_status; quiet reference matches remain available through search. Without search, the news-activity directory excludes measured-zero coverage rows. For the cross-source candidate list with per-source availability, use /api/v2/search. Native non-Latin-script matching is not yet complete, so use a common Romanized or English spelling for Cyrillic, Chinese and other non-Latin names for now. Native-script search support is on the way.

Response: Structured JSON response · MCP tool: search_entities

One Actor in, one time-ordered, cited chronology out: public-list membership evidence as a change log (list_added / list_removed), public offices held (office_start / office_end), FARA foreign-agent registrations, federal awards and the coded event stream — fusing news and registry records when a confirmed identity bridge exists. Missing bridges are disclosed in meta.coverage_note, with unmeasured coverage NULL. flags carries the cross-lane statecraft conjunctions (an office-holder who is listed, a designation that landed while in office, a sanctioned facility owner, a foreign agent for a sitting official) with receipts in flag_details; the dossier does not return a facility inventory. {entity_id} accepts a name, a spine e_ id, a wiki: or llm: id or a Wikipedia URL. Confirm the intended parent, subsidiary or person in Search and reuse its identifier. With as_of dated facts are filtered to on-or-before that date; offices use the office dates the source publishes. Unknown coverage is NULL, never a fabricated 0, and every item carries source_key, attribution, evidence_url and date_precision. List items also carry date_basis: publisher_listing uses a publisher-supplied listing date, first_observed uses our first observation, and observed_change uses our change-detection snapshot. An observed addition or removal is not a publisher designation or removal date. Legacy USAspending search records carry reported performance-start dates, explicitly labeled in the timeline, rather than award-action dates. Current memberships and identity links do not reconstruct a complete historical knowledge snapshot; meta.no_lookahead remains false. Reporting is linked-Story coverage, not proof of direct participation or material impact. Timeline items are bounded per source and summary totals may exceed the preview. Economic-statecraft INTELLIGENCE — not a compliance or screening control (see meta.disclaimer).

Response: EntityDossierResponse · MCP tool: get_entity_dossier

An entity's corporate hierarchy resolved through our spine: direct_parent, ultimate_parent, children and child_count. Accepts the same identifiers as the rest of the API — a name, an e_ id, a wiki: id or a wikipedia_url — and additionally a bare 20-character LEI, so the identifier you searched with works at this hop too. **Read the coverage block before the hierarchy.** lei_present: false means the entity carries no LEI in our crosswalk — a coverage gap, NOT evidence the entity has no parent. reporting_exception carries the reason a filer gave for not naming a parent (for example NO_KNOWN_PERSON), which is a DECLARED absence and materially different from an unknown one. child_count is null, never 0, when the requested direction excluded children. Corporate hierarchy as reported to the Global LEI System: accounting consolidation under IFRS/US-GAAP, not percentage ownership and not beneficial ownership. Natural persons are out of scope, and reporting is partial — an absent parent usually means the filer declared a reporting exception rather than that none exists. Gated on the existing can_use_exposure entitlement; the LEI itself is ungated. Point-in-time (as_of) is not supported for this source.

Response: Structured JSON response

Fetch one Entity profile with linked Stories and Events. Admin/internal callers can set include_tone=true to join cached Entity Tone coverage; when no tone score exists, the response returns tone_status=not_available rather than hiding the entity or treating missing tone as neutral.

Response: success, data

The full Level-1 record for a single LEI plus its Level-2 relationships, any declared reporting exceptions, and its LEI↔ISIN mappings. A structurally impossible LEI returns 400 INVALID_LEI (it fails the ISO 17442 check digit); a well-formed LEI we do not hold returns 404. Corporate hierarchy as reported to the Global LEI System: accounting consolidation under IFRS/US-GAAP, not percentage ownership and not beneficial ownership. Natural persons are out of scope, and reporting is partial — an absent parent usually means the filer declared a reporting exception rather than that none exists. Plan-gated: requires the can_use_gleif entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries meta.attributions[] with GLEIF's required non-endorsement notice.

Response: Structured JSON response

The GLEIF Global LEI Index — 3.39M legal entities with their registered name, jurisdiction, entity and registration status, legal form and registration authority, served close to as-published. **At least one filter is required**: the feed covers 3.39M records, so an unfiltered listing is refused with 400 FILTER_REQUIRED rather than served slowly. name matches the normalized legal name exactly or by prefix (never a substring scan). Plan-gated: requires the can_use_gleif entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries meta.attributions[] with GLEIF's required non-endorsement notice.

Response: Structured JSON response

Resolve an LEI to its issued ISINs, or an ISIN back to its LEI. One of lei or isin is required — the mapping table holds ~9M rows and an unfiltered listing is refused with 400 FILTER_REQUIRED. Plan-gated: requires the can_use_gleif entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries meta.attributions[] with GLEIF's required non-endorsement notice.

Response: Structured JSON response

Parent/child relationship records as filed with the Global LEI System. lei matches EITHER endpoint. Note the direction convention in the source data: the start node is the CHILD and the end node is the PARENT. Corporate hierarchy as reported to the Global LEI System: accounting consolidation under IFRS/US-GAAP, not percentage ownership and not beneficial ownership. Natural persons are out of scope, and reporting is partial — an absent parent usually means the filer declared a reporting exception rather than that none exists. Plan-gated: requires the can_use_gleif entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries meta.attributions[] with GLEIF's required non-endorsement notice.

Response: Structured JSON response

Resolve a company name, ticker, or CIK to SEC filing identities and terminal spine entities.

Response: success, query, resolved · MCP tool: filings_resolve

XBRL structured financial facts for a filer — a concept time series for exposure sizing. Requires a plan with SEC filings access (can_use_filings) — see Pricing for the plans that include it.

Response: success, cik, data, pagination, applied_filters

Subsidiary / supplier / customer / jurisdiction edges for a filer, derived from filing text through GDELT Cloud's proprietary AI pipeline and resolved to entity_ids with evidence. Requires a plan with SEC filings access (can_use_filings) — see Pricing for the plans that include it.

Response: success, cik, data, pagination, applied_filters

A filer's identity, ticker, resolved entity_id, recent filings, and XBRL financial highlights. Requires a plan with SEC filings access (can_use_filings) — see Pricing for the plans that include it.

Response: success, cik, company_name, ticker, entity_id, recent_filings, risk_factors, business, xbrl_highlights

Dated 8-K material corporate events (M&A, material agreements, executive changes, bankruptcies, delistings, impairments) extracted from 8-K bodies, with counterparties resolved into the entity spine. Requires a plan with SEC filings access (can_use_filings) — see Pricing for the plans that include it.

Response: success, data, pagination, applied_filters

List the SEC EDGAR filing index by company (CIK), form type, name, and date window. Requires a plan with SEC filings access (can_use_filings) — see Pricing for the plans that include it.

Response: success, data, pagination, sort, applied_filters

Rollup of filings by form type, date, or filer — counts + distinct filers. Requires a plan with SEC filings access (can_use_filings) — see Pricing for the plans that include it.

Response: success, group_by, data, applied_filters

Unified physical-asset directory — GEM energy and heavy-industry sites, WPI ports and AI data centers, deduped to one facility per real-world site.

Response: FacilityCard · MCP tool: facilities_search

Returns a canonical physical site with unit count, unit identifiers and status breakdown. A legacy registry-unit id resolves to the same parent site.

Response: FacilityCard · MCP tool: facilities_get

Lists the source registry units belonging to a canonical physical site. A canonical site id or any legacy unit id may identify the site.

Response: success, data

A facility fused with its OWNER's media coverage, plus optional government exposure. Returns owner_events — events about the owner, NOT events located at the site. When the owner cannot be resolved or cannot be bridged to the news layer, the arrays are null rather than empty, so "we did not look" is never mistaken for "we looked and found nothing". Coverage unions the checked owners or their recorded parents, preserving typed paths, stakes and sources in owner.coverage_paths; a minority ownership path does not establish control. Summary counts describe the returned Event preview and its linked Stories, not all matches. Multiple coverage entities leave the legacy singular owner id/name null; optional government footprints are not aggregated across them. Oversized or unavailable scopes are reported explicitly.

Response: Structured JSON response · MCP tool: facilities_context

Fetch one Energy asset by tracker and GEM ID. The response includes the canonical asset card plus a raw source record containing tracker-specific fields.

Response: success, data, raw

Return map-ready Energy asset data. Without a single explicit country filter, the endpoint returns aggregate country-centroid rows. With exactly one country filter and no region or continent, it returns fine-grained asset pins capped by map_limit/fine_grained_limit.

Response: success, mode, data, filters_echo, applied_filters

Search Global Energy Monitor energy-infrastructure assets across all 15 trackers. Returns clean asset cards with native capacity, MW capacity where meaningful, normalized geography, ownership arrays, GEM Wiki URLs, and detail/API links.

Response: success, data, pagination, sort, filters_echo, applied_filters

Aggregate counts and MW rollups across Energy assets. Summary endpoints use structured filters only. capacity_mw fields are meaningful for power-generation trackers; constrain tracker when comparing capacity across unit families.

Response: success, group_by, data, applied_filters

Fetch one Global Energy Monitor ownership entity by GEM Entity ID, including parent IDs, external IDs, and a portfolio summary across Energy assets. Optional include_exposure=true adds plan-gated risk/exposure fields — requires can_use_exposure (see Pricing for the plans that include it).

Response: success, data

Search the Global Energy Monitor ownership registry for canonical owner entities. Use this endpoint to resolve a company, government owner, person, or investment vehicle to a GEM Entity ID before calling owner portfolio or exposure endpoints.

Response: success, data, pagination, applied_filters

Aggregate vessel activity over an area, bucketed by hour or day — distinct vessels, total + moving positions, and average/max speed per bucket. Generalizes /transits to arbitrary geography (chokepoint, bounding box, or proximity). The "is this area's traffic anomalous vs the baseline" view. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Historical / baseline surface: reads raw AIS positions directly (not the derived rollups). Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 30 days; defaults to the trailing 14 days. Bucket auto-selects hour for spans ≤2 days, otherwise day.

Response: success, bucket, data, pagination, applied_filters

One vessel by IMO number: identity, last-known position, and the matched Global Energy Monitor LNG carrier (when one exists). Position is LAST-KNOWN ONLY — no raw track. Returns 404 when no vessel identity exists for the IMO. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Forward-accruing: position history begins at launch (June 2026). Terrestrial AIS only (no satellite).

Response: success, imo, identity, last_position, gem_carrier

The maritime risk layer — fuses each chokepoint's AIS coverage confidence (live / sparse / dark) and 24h/7d transit activity with GDELT conflict events (last 7 days) in its bordering countries, plus nearby flagged-energy-asset exposure. Surfaces the 'blind spot': high conflict signal but no vessel coverage. Derived rollups + events only (no raw positions). Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Each row scores a risk_level (critical / elevated / watch / quiet) and rows are risk-ranked. Envelope: { success, data, summary, applied_filters }.

Response: success, data, summary, applied_filters

Spatial density grid (heatmap) of position and vessel counts per lat/lon cell within an area. Shows where traffic concentrates. AREA REQUIRED — pass bbox, near, or near_gem_id. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Historical / baseline surface: reads raw AIS positions directly. Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 7 days; defaults to the trailing 1 day.

Response: success, cell_deg, data, pagination, applied_filters

Dwell episodes — completed arrival→departure stays at maritime chokepoints, derived from terrestrial AIS. Each row is one vessel's stay with its dwell duration. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Forward-accruing: episodes begin accruing at launch (June 2026) — no historical backfill. Derived-only: no raw position track. Terrestrial AIS only (no satellite). Filtered by departure time; date windows are capped at 30 days and default to the trailing 7 days.

Response: success, data, pagination, applied_filters

AIS-dark gaps — intervals where a vessel stopped broadcasting AIS then reappeared, derived from terrestrial AIS coverage. Each row is one gap with the last-known position before it went dark. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Forward-accruing: gaps begin accruing at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite); a gap reflects loss of terrestrial reception, not necessarily a deliberate dark event. Filtered by gap-end time; date windows are capped at 30 days and default to the trailing 7 days.

Response: success, data, pagination, applied_filters

Port-level disruption intelligence — geo-fuses the WPI ports reference with GDELT events near each port (within event_radius_km over the last days): relevant-event volume, conflict signal, a 7d-vs-baseline anomaly ratio, recent headlines, nearby flagged-energy-asset exposure, and AIS-coverage context. Scope by country, terminal type, name, or proximity; with no scope it defaults to strategic ports (LNG/oil terminals + large harbors). Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Each row scores a pulse_level (critical / elevated / active / quiet) and rows are risk-ranked. Envelope: { success, data, summary, applied_filters }. Pulse rubric: critical = at least 5 conflict Events; elevated = 1–4 conflict Events; active = no conflict Events but at least one other relevant Event; quiet = no relevant Events. Relevant-event volume does not override a conflict-based level. relevant_events: Events within event_radius_km that are either conflict-family Events or carry one of the published maritime, infrastructure, trade, sanctions, energy, logistics, port, shipping, pipeline, customs, smuggling, or commodity relevance tags.

Response: success, data, summary, applied_filters

The open-data ports reference (NGA World Port Index) — ~3,800 ports with coordinates, UN/LOCODE, harbor size/type/use, max vessel draft, channel depth, and container / oil / LNG terminal facilities. Filter by country, harbor size, terminal type, name, or proximity to a point / GEM energy asset. This is reference data (no date window). Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. When a proximity center is set (near, near_gem_id), each row carries distance_km and results sort nearest-first. Standard envelope: { success, data, pagination, applied_filters }.

Response: success, data, pagination, applied_filters

⚠️ RAW position points (the actual AIS track) inside an area over time — each row a single fix (time, position, speed, course, nav status). AREA REQUIRED — pass chokepoint, bbox, near, or near_gem_id. Keyset-paginated: follow the opaque next_cursor to stitch a long window into pages rather than one giant response. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Historical / baseline surface: reads raw AIS positions directly. Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 7 days; defaults to the trailing 1 day.

Response: success, data, pagination, applied_filters

Hourly vessel-flow rollup for maritime chokepoints, derived from terrestrial AIS. Each row is one chokepoint·hour with vessel counts and average speed. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Forward-accruing: signals begin at launch (June 2026) — there is no historical backfill. Derived-only: no raw position track is exposed. Terrestrial AIS only (no satellite). Date windows are capped at 30 days; defaults to the trailing 7 days when no dates are given.

Response: success, data, pagination, applied_filters

⚠️ RAW position track for a single vessel by IMO — the literal 'this ship over time': every AIS fix (time, position, speed, course, heading, nav status) across the window, time-ordered. Keyset-paginated: follow the opaque next_cursor to stitch a long window into pages rather than one giant response. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Historical / baseline surface: reads raw AIS positions directly. Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 30 days; defaults to the trailing 7 days.

Response: success, imo, data, pagination, applied_filters

Current vessels with their last-known position and identity, derived from terrestrial AIS. Positions are LAST-KNOWN ONLY — there is no raw position-track endpoint. This is current state, so it takes no date window. Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it. Forward-accruing: vessel state begins at launch (June 2026). Terrestrial AIS only (no satellite).

Response: success, data, pagination, applied_filters

Country publication aggregates and hourly evidence from the shared activity journal. Additions, updates and linked entities are separate metrics. Facility additions count published registry records (units), not newly built or deduplicated physical sites; country context inventories expose site and unit totals separately. All matching countries are included; this map is independent of evidence pagination. Source collection gaps remain explicit: unknown or withheld source counts are null in both country and hourly rows. meta.coverage.window_complete distinguishes an initialized journal from history covering the selected window; hourly_window_complete covers the entire timeline day. Actor-direction edges use Event occurrence dates, separately from publication activity. meta.edges_coverage exposes availability, status and oldest serving snapshot as_of; unavailable snapshots do not imply zero relationships.

Response: CountryActivityCard · MCP tool: get_countries

Country activity, dated economic/resource fundamentals, facilities and political-office inventories with evidence links. Unknown values remain null. Country association does not imply citizenship or headquarters. Counts of people, office-holder records, facilities and units are qualified separately.

Response: CountryContextCard · MCP tool: get_country

Vintaged Atlas GPR readings for one explicit geographic level and place. Every accepted query parameter is declared here; undeclared geographic shortcuts such as country= fail with UNKNOWN_PARAM rather than returning the World series. Country own_coverage rows may include a separate best_effort calculation below the daily count floor. The official pulse remains null; the estimate uses the same coder-matched denominator, carries no band or trend claim, and is absent for zero coverage, open UTC days, missing or pooled baselines. world_corpus gates are unchanged.

Response: success, series_id, level, geo_id, methodology_version, construction, baseline, coverage_floor, coverage_floor_basis, data, pagination · MCP tool: intelligence_gpr

A 0–100 condition score with explicit dynamic and structural axes. Sparse Event windows retain null dynamic scores. Available annual WDI/WGI/V-Dem indicators can supply a structural-only headline, marked best_effort with its evidence note, indicator count and vintage. Headline insufficient_data means neither axis has a score. Annual indicators use fixed absolute anchors; dynamic indicators use frozen cross-country or absolute references. as_of constrains dynamic observations, not the latest annual indicators or frozen normalization; this is not a fully point-in-time structural backtest.

Response: Structured JSON response · MCP tool: intelligence_posture

Per-country coded-event coverage over a trailing window, and therefore which country-level Atlas products (Pulse, Posture) each country is dense enough to serve today. Read it BEFORE treating a null Atlas reading as calm: below the floors means unknown, not quiet. All 206 countries are enumerated, so a country with no coverage is disclosed rather than omitted, and summary always describes the whole world even when the rows are filtered. The window is always trailing and always ends today — there is no historical or vintaged read here, which is why date, date_start, date_end and as_of are not parameters of this endpoint.

Response: Structured JSON response

Discover the admin1 (state / province / oblast) values available for one country, measured over a trailing window of the settled Events table and canonicalised to exactly the tokens the admin1 filter on /api/v2/events and /api/v2/stories accepts — so discover→filter round-trips without guessing spellings. Each region appears ONCE, under whichever spelling carries the most events, with that count attached; a trailing administrative suffix ("Donetsk" vs "Donetsk Oblast") is folded on both sides by the filter, so either spelling returns the same events. This endpoint is intentionally country-scoped and does not return the full admin1 catalog.

Response: Admin1DiscoveryResponse · MCP tool: list_admin1

China overseas development-finance projects (AidData GCDF) — amounts, sector, status, financiers; joinable to the live event stream by country. Requires a plan with China development finance access (can_use_china) — see Pricing for the plans that include it.

Response: success, data, pagination, sort, applied_filters

Rollup of China overseas development finance by country, sector, status, commitment year, flow class, or funding intent — counts + total committed USD. Requires a plan with China development finance access (can_use_china) — see Pricing for the plans that include it.

Response: success, group_by, data, applied_filters

Point-in-time observations for a single series. Optional as_of selects the vintage known on/before that date (ALFRED — no look-ahead); otherwise the latest vintage is returned. When no dates are given, returns the most-recent observations across the full available history, bounded by limit — page further back via next_cursor; there is no fixed trailing window. Discover a valid series_id via GET /api/v2/macro/series. Requires a plan with Macro & economic data access (can_use_macro) — see Pricing for the plans that include it.

Response: success, series_id, data, pagination, applied_filters, meta

Rollup of the catalog by source agency and release, with series counts. Requires a plan with Macro & economic data access (can_use_macro) — see Pricing for the plans that include it.

Response: success, data, applied_filters, meta

Series catalog detail plus the most recent 24 observations (latest vintage). An unknown or quarantined series_id returns 404 with a message pointing to GET /api/v2/macro/series and the catalog. Requires a plan with Macro & economic data access (can_use_macro) — see Pricing for the plans that include it.

Response: success, series, recent_observations, meta

List the FRED economic time-series catalog by title/ID search, agency, frequency, and seasonal adjustment. Call with no filters to enumerate the full curated catalog (ordered by popularity) — this is the way to discover a valid series_id. Quarantined (third-party copyrighted) series are never returned. Requires a plan with Macro & economic data access (can_use_macro) — see Pricing for the plans that include it.

Response: success, data, pagination, applied_filters, meta

Recall-first restricted-party candidate retrieval with explicit match evidence. Retrieval similarity is not an identity probability and is exposed separately from match confidence.

Response: ScreeningMatchResponse · MCP tool: screening_match

Precomputed entity and facility exposure through sanctions, China, or state-ownership chains. Numeric stake filters apply to effective chain stake, never the direct asset-owner percentage alone.

Response: ExposureResponse · MCP tool: exposure_search

Catalog of the restricted-party list sources we ingest — issuer, jurisdiction, category, publisher provenance, refresh cadence, whether the source publishes natural persons, and the current entry count. The index for /api/v2/lists/entries and /api/v2/screening/match: every source_key here with ingested: true is a legal list= value there, and only those are. Catalogue fields that the crawler lane measures (category, publisher, publisher_country, official, licence, last_crawled, coverage_start) are null on a source that has not published them — never a fabricated default. includes_individuals is MEASURED (the source has projected at least one person row), so a person-screening caller can branch on it.

Response: ListsCatalogResponse

Search the entries on the restricted-party lists — by name or alias, country, programme, or resolved entity — current or point-in-time. Each entry carries its aliases, entity_kind (entity | vessel | aircraft | individual), programmes, legal basis, cross-source ids and our first/last observation dates. A natural-person row (entity_kind: individual) carries birth_year and topics and NEVER addresses — the served-person contract withholds them. A country filter is honoured best-effort where a source does not populate the structured country field, and the response says so in coverage_warning: treat a miss as "no match on file", not "not sanctioned".

Response: ListEntriesResponse

The daily diff feed for the restricted-party lists — who was added, removed or changed on each snapshot date. Snapshot dates are OUR observation dates; the feed begins at coverage_window.start on /api/v2/screening/match. Without a window it returns the most recent changes first.

Response: ListChangesResponse

Public political offices — legislative seats, cabinet posts, heads of state and government, courts, security and financial offices and IGO posts — one row per office, dataset-independent, with holder counts. Scope and branch are derived from the source's gov.* topics so they are closed, filterable vocabularies. holders_current is NULL, never 0, when no source asserts currency for the office. Actor context for geopolitical analysis; NOT a PEP or sanctions-screening tool.

Response: OfficeCard · MCP tool: offices_search

One office by id — the Wikidata QID (Q…) or the p_… id /api/v2/offices serves — with a capped preview of its holders ordered current → ended → unknown. holders_truncated says when to walk holders_url instead. A name is not looked up here: resolve it on the list first.

Response: OfficeCard · MCP tool: office_get

The valid-time roster of one office: every (holder, term) the publishers assert, ordered current → ended → unknown and most recent start first. Two datasets asserting one term are ONE row naming both sources. Holders are terminal spine ids collapsed through the arbiter; a holder the binder did not mint is served with entity_id: null and its holder_source_ref, never dropped. Pages by an opaque keyset cursor; a token from a different sort or filter set is refused with 400 CURSOR_STALE rather than answered plausibly.

Response: OfficeHolderCard · MCP tool: office_holders

Every public office one entity has held, as the publishers assert it. {entity_id} accepts a spine e_… id, a news wiki: / llm: id, or a wikipedia_url, resolved through the same arbiter every other surface uses — a merged-away alias still finds its rows. An entity that resolves but holds no office answers data: [] with meta.checked: true; one with no spine identity to look under answers data: [] with meta.checked: false; one that does not resolve at all is 404 ENTITY_NOT_FOUND, never an empty 200.

Response: OfficeHolderCard · MCP tool: entity_offices

US federal award exposure for an entity — USAspending prime awards (contracts + grants) resolved to the entity spine. Look a subject up three ways (at least one is required): a resolved spine entity_id (entity=), a SAM.gov Unique Entity Identifier (uei=), or a fuzzy recipient name (recipient=). Returns an aggregate summary (total obligated USD, award + recipient counts) with a per-UEI recipient_rollups breakdown (top 25 by obligated USD, each with its awarding agencies and first/last action dates), plus the recent awards timeline — every row cited to its USAspending permalink. **D&B carve-out:** keyed on the SAM.gov UEI only — Dun & Bradstreet's DUNS number and corporate-family (parent) tree are never ingested or surfaced. Plan-gated: requires the can_use_gov entitlement (Markets plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Reads are bounded key-prefix lookups on the current award snapshot (no all-time scan).

Response: query, summary, awards, meta, cross_source

US foreign-influence graph — DOJ FARA registrations linking a US registrant (law/lobby/PR firm) to the foreign principal it represents, resolved to the entity spine. Filter by a resolved entity (matches EITHER side of the link), a fuzzy registrant or foreign_principal name, or a country; adversary_only restricts to adversary governments and sanctioned_only to the killer cross — US firms registered as agents for a **sanctioned** entity (the foreign principal is matched to our screening lists — OFAC SDN / BIS Entity / DoD 1260H / OFAC CMIC / UK — with the specific fp_sanction_lists + fp_sanction_programs). At least one filter is required. Plan-gated: requires can_use_gov (Markets plan and up); non-entitled plans receive 403 PLAN_REQUIRED. US Public Domain (DOJ NSD FARA eFile).

Response: query, summary, links, meta, cross_source

Epoch AI chip-sales rollup (CC-BY 4.0) — cumulative installed compute by chip designer (H100-equivalent), unit counts, and power draw (MW), at the latest reported window per manufacturer. Sorted by installed compute descending. Requires a plan with AI compute & models access (can_use_epoch_ai) — see Pricing for the plans that include it. Filter by chip_manufacturer (the endpoint's sole filter); any other query param is surfaced back in applied_filters.ignored rather than silently applied.

Response: success, data, pagination, applied_filters

Epoch AI company tracker (CC-BY 4.0) — the tracked AI labs with latest valuation, annualized revenue, total equity funding, staff count, and company type. Latest financials are derived from the dated time-series (most recent closed funding round for valuation). Sorted by valuation descending. Requires a plan with AI compute & models access (can_use_epoch_ai) — see Pricing for the plans that include it. This endpoint takes no filter params beyond pagination — any other query param (e.g. search, org) is surfaced back in applied_filters.ignored rather than silently applied.

Response: success, data, pagination, applied_filters

Epoch AI data-center registry (CC-BY 4.0) — the largest AI compute clusters with power (MW), H100-equivalent compute, capital cost ($B), owner, chip types, and named users. Rows sort by compute (H100e) descending. Includes a per-country rollup (by_country) and dataset totals (totals). Requires a plan with AI compute & models access (can_use_epoch_ai) — see Pricing for the plans that include it. Response echoes applied_filters.

Response: success, data, by_country, totals, pagination, applied_filters

Epoch AI ML-hardware catalog (CC-BY 4.0) — accelerators (GPU / TPU / NPU / ASIC …) with manufacturer, release date, TDP, memory, process size, and FP16/FP8 throughput. Rows sort by release date descending. Requires a plan with AI compute & models access (can_use_epoch_ai) — see Pricing for the plans that include it. Response echoes applied_filters.

Response: success, data, pagination, applied_filters

Epoch AI notable-models catalog (CC-BY 4.0). Each model carries its developer, domain, parameters, training compute (FLOP), training hardware, frontier flag, and accessibility. Rows can be sorted by publication date or training compute. Requires a plan with AI compute & models access (can_use_epoch_ai) — see Pricing for the plans that include it. Boolean fields (frontier_model, open_weights) are real JSON booleans, training_compute_flop is de-artifacted, and the response echoes applied_filters (unknown params surface in applied_filters.ignored). This product uses data from Epoch AI (CC-BY 4.0).

Response: success, data, pagination, applied_filters

Every vocabulary the API validates against, with the value-space of each — closed (the complete authoritative set, safe to switch on), observed (a dated measurement of what the corpus currently holds, never an allowlist) and identifier (a key with a format and a resolver, never enumerated). Carries a sha256 you can pin and diff in CI to detect a vocabulary change before it reaches your code. Requires a key so use stays attributable, and is NOT metered — checking a value before spending a query unit should not cost a query unit.

Response: success, data

The contract-governed endpoints and every parameter each one accepts — names, aliases, bounds, defaults, the vocabulary a value is validated against, and the params deliberately rejected with what to use instead. Served from the same descriptors the API imports at request time, so it cannot describe behaviour the server does not have. Not metered.

Response: success, data

The query-unit cost model and this key's current allowance and measured consumption. Pricing remains available when usage aggregation is delayed: usage.measurement_status is fresh, stale, or pending; unknown consumption, remaining allowance, and percentages are null rather than zero or unlimited. Usage is pooled at the organization when the key belongs to one. Monitor execution is listed separately with a zero multiplier because scheduled Monitor checks do not consume Query Units. Not metered.

Response: success, data

Lists the active organization's shared Monitors together with the caller's current Monitor capabilities (plan, can_create, can_activate, active_monitors, total_monitors, max_monitors, available_monitor_slots, min_monitor_frequency, legacy_can_execute, can_use_monitor_webhook). The listing is complete and takes no filter or pagination parameter. max_monitors limits enabled schedules only; paused saved Monitors do not consume a slot. Monitor execution does not consume query units.

Response: success, monitors, capabilities

Returns one organization-shared Monitor: its canonical subject, criteria, schedule, delivery state and legacy compatibility marker. A malformed id is a 404, not a 500.

Response: success, monitor

Lists the Monitor's triggered runs, retained for seven days. result_count, retained_row_count and results.length describe three different quantities — read them as such. This is the only Monitor operation that takes query parameters, and it takes exactly two.

Response: success, monitor, runs, total, limit, offset

Returns one triggered run with its bounded canonical matches and exact replay instructions. Follow every cursor in replay_requests and then apply exact_window_filter — the matches embedded in the run are a bounded sample, not the run's full result set.

Response: success, monitor, run

Pages the COMPLETE list of items one triggered run matched, as it was at trigger time, with the current state of each hydrated live. GET /api/v2/monitors/{id}/runs/{runId} embeds a bounded SAMPLE of cards; this operation walks the whole matched set. Each entry carries as_triggered — exactly what the email or webhook asserted, frozen and never re-derived — alongside current, the live card, and a status of unchanged, updated, superseded or gone. superseded means a Story was merged away by same-day de-duplication; follow the id to GET /api/v2/stories/{story_id}, which answers 404 STORY_MERGED with the replacement id. Read result_count, retained_match_count and matched_items_truncated together: when the run matched more items than the writer retains, result_count remains the exact total and the retained list is a prefix that says so. Runs are retained for seven days.

Response: success, data

Downloads every retained matched item for a Monitor run as UTF-8 CSV. The export includes the frozen as-triggered fields, the current hydrated card, reconciliation status, and run-level counts. It takes no query parameters and may contain fewer rows than result_count when the writer reports matched_items_truncated=true.

Response: success, data

Fetch one Monitoring Brief: status, the original input, the structured document (Monitoring Brief content), citations, the evidence appendix, and report URLs. A still-running Brief is reconciled first. Requires a plan with Briefs access.

Response: id, title, brief_type, status, created_at, updated_at, error_message, input, document, citations, appendix, public_url, web_url

List the caller's Monitoring Briefs with status and report URLs. Still-running Briefs are reconciled first. Requires a plan with Briefs access.

Response: briefs