> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Facility context
> 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".
These return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.
- `as_of` → 400 UNSUPPORTED_PARAM. Facility ownership is not vintaged — the directory records the latest known owner and prior owners are not yet reconstructable as-of, so an as_of result here would not be reproducible. Use instead: `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/*?as_of=`.
## OpenAPI
````yaml /api-reference/openapi-v2.json get /api/v2/facilities/{facility_id}/context
openapi: 3.0.3
info:
title: GDELT Cloud API v2
version: 2.0.0
description: >-
Clean v2 REST API for generated GDELT Cloud structured Events, clustered
Stories, linked Entities, summaries, admin1 discovery, significance ranking,
and paginated article evidence.
Event significance is a family-scoped weighted blend, renormalized so every
event family spans a true 0-1: each event's raw total is divided by the
maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90,
other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article
evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled
by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20,
systemic importance 0.15, propagation potential 0.10, market sensitivity
0.10. When magnitude is unmeasured its term AND its 0.20 weight are both
dropped. The four CAMEO+ metrics are rubric scores produced by published
formulas - ordinal ranking signals, not measurements, probabilities, or
predicted price moves. goldstein_scale is one canonical public metric,
populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful.
Story linked_event_count is a Story-to-Event link aggregate, not a distinct
Event total.
servers:
- url: https://gdeltcloud.com
description: Production
- url: http://localhost:3000
description: Local development
security:
- ApiKeyAuth: []
tags:
- name: Events
description: Coded CAMEO+ / conflict events — search, fetch, and summarize.
- name: Stories
description: Clustered narratives (stories) and their articles.
- name: Entities
description: >-
People & organizations — resolve a name to an entity, then fetch its
profile and tone.
- name: Unified Search
description: >-
One fuzzy lookup across every id-space — start here with a name, take the
entity id, then reuse it on every other surface. This is the resolver the
rest of the API assumes you called first.
- name: Media Intelligence
description: >-
Press-coverage tone over time and share of voice against a peer set.
Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social
signal is an admin-only preview.
- name: Facilities
description: >-
Unified physical-asset directory — GEM energy assets, World Port Index
ports and Epoch AI data centers on one keyed surface, resolved to spine
owners. Requires the `can_use_facilities` entitlement.
- name: Geography
description: Admin-1 geography lookups.
- name: Government
description: >-
US federal awards (USAspending) and foreign-influence registrations (DOJ
NSD FARA), resolved onto the entity spine. Requires the `can_use_gov`
entitlement.
- name: Filings
description: >-
SEC EDGAR filings, XBRL financials, and relations extracted from filing
text. Requires the `can_use_filings` entitlement.
- name: Reference Data
description: >-
The GLEIF Global LEI Index — legal-entity reference data, consolidation
relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif`
entitlement.
- name: Energy
description: Global Energy Monitor assets + ownership registry.
- name: AI Compute
description: >-
Epoch AI datasets — models, hardware, data centers, companies and chip
sales. Requires the `can_use_epoch_ai` entitlement.
- name: Macro Finance
description: >-
FRED economic time series — catalog, point-in-time observations and
releases. Requires the `can_use_macro` entitlement.
- name: Screening and Reference
description: >-
Restricted-party lists, name screening and ownership-chain exposure.
Requires the `can_use_screening` / `can_use_exposure` entitlement.
Analytical coverage, not an audit-grade compliance control.
- name: China
description: >-
China overseas development finance (AidData GCDF). Requires the
`can_use_china` entitlement.
- name: Maritime
description: >-
AIS-derived vessel flow — chokepoint transits, last-known vessel
positions, carriers, dwell and AIS-dark gaps. Terrestrial AIS only, so
coverage thins in open ocean. Requires the `can_use_maritime` entitlement.
- name: Atlas Intelligence
description: >-
Geopolitical-risk and posture indices computed from GDELT Cloud’s own
coded events, normalized to each place’s own frozen baseline.
- name: Briefs
description: Source-backed monitoring briefs.
- name: Meta
description: >-
Machine-readable discovery: the value vocabularies, the endpoint
contracts, and the query-unit cost model. Unmetered, so a client can check
before it spends.
paths:
/api/v2/facilities/{facility_id}/context:
get:
tags:
- Facilities
summary: Facility context
description: >-
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".
These return a 400 naming the reason and the alternative, so a filter
that cannot work fails loudly instead of returning rows that ignore it.
- `as_of` → 400 UNSUPPORTED_PARAM. Facility ownership is not vintaged —
the directory records the latest known owner and prior owners are not
yet reconstructable as-of, so an as_of result here would not be
reproducible. Use instead: `/api/v2/intelligence/gpr?as_of=`,
`/api/v2/macro/*?as_of=`.
operationId: get-facility-context-v2
parameters:
- name: facility_id
in: path
required: true
schema:
type: string
description: The facility id.
- name: days
in: query
required: false
schema:
type: string
default: 7
description: >-
Owner-coverage window in days, max 30. Also accepts: `window`. Note:
validation is owned by the endpoint service because it depends on
composed or cross-parameter state; the published error semantics
above still apply.
example: '30'
x-aliases:
- window
- name: date_start
in: query
required: false
schema:
type: string
format: date
description: >-
Explicit start of the owner-coverage window. Also accepts:
`start_date`. Note: validation is owned by the endpoint service
because it depends on composed or cross-parameter state; the
published error semantics above still apply.
example: '2026-08-01'
x-aliases:
- start_date
- name: date_end
in: query
required: false
schema:
type: string
format: date
description: >-
Explicit end of the owner-coverage window. Also accepts: `end_date`.
Note: validation is owned by the endpoint service because it depends
on composed or cross-parameter state; the published error semantics
above still apply.
example: '2026-08-04'
x-aliases:
- end_date
- name: limit
in: query
required: false
schema:
type: integer
default: 10
minimum: 1
maximum: 50
description: >-
Maximum owner events to attach. Default 10, max 50. Note: validation
is owned by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply.
example: '10'
- name: include
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- gov
description: >-
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. Full value list:
https://docs.gdeltcloud.com/reference/enums#facility_context_include
example: gov
responses:
'200':
description: Success
'400':
description: Invalid parameter
'401':
description: Missing or invalid API key
'403':
description: Plan does not include this surface
'429':
description: Quota or rate limit exceeded
'500':
description: Server error
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: gdelt_sk_...
description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'
````