> ## 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.

# Government

> Entity government-exposure — US federal awards (USAspending) resolved to the entity spine, keyed on SAM.gov UEI, so an entity search returns its federal award footprint fused to the live graph.

The Government API turns a resolved entity into its **US federal footprint** — what the
federal government *pays* it — on the same entity spine used across the rest of the API.
Federal awards are a first-party, public-domain source, keyed to the spine so an entity
search returns its award timeline fused to the live Events / Stories / Entities / Facilities
graph:

| Source                         | Key → spine                                      | What it contributes                                                                                               | License          |
| ------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ---------------- |
| **USAspending** federal awards | SAM.gov **UEI** → entity\_id                     | Prime contracts + grants: obligated \$, awarding agencies, action dates, per-UEI rollup                           | US Public Domain |
| **FARA** foreign agents        | registrant + foreign-principal name → entity\_id | Who represents whom: US agent ↔ foreign principal, country, active/terminated, **crossed to our sanctions lists** | US Public Domain |

Because recipients resolve to spine `entity_id`s, government spending joins the graph:
from one entity you can pivot to its federal awards, then to the facilities it owns and the
events near them. That fused path is the join a standalone procurement viewer can't offer.

<Info>
  The Government endpoints are **plan-gated** — they require the `can_use_gov` entitlement,
  included on the **Markets plan and up**. Plans without it receive a clean `403 PLAN_REQUIRED`.
</Info>

<Warning>
  **D\&B carve-out.** USAspending recipient records are keyed on the SAM.gov **UEI** only. Dun &
  Bradstreet's **DUNS** number and the D\&B corporate-family (parent) tree are proprietary and
  are **never ingested or surfaced** by this API — you get the public-domain award facts and the
  UEI, not the licensed D\&B graph.
</Warning>

## Federal Awards

`GET /api/v2/gov/awards` — USAspending prime awards for an entity. Look a subject up by a
resolved `entity` id, a SAM.gov `uei`, or a fuzzy `recipient` name (at least one required).
Returns an aggregate `summary` (total obligated $, award + recipient counts), a per-UEI `recipient_rollups` breakdown (top 25 by obligated $, each with its awarding agencies and
first/last action date), and the recent `awards` timeline — every row cited to its
USAspending permalink.

| Param       | Description                                                                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `entity`    | Resolved spine entity id (`e_…` / `wiki:…` / `cik:…`). Returns that entity's awards. A bare name returns `400 INVALID_ENTITY_ID` — [resolve it](/api-reference/concepts#finding-an-entity-when-you-dont-know-the-exact-name) via `GET /api/v2/search` first. |
| `uei`       | A SAM.gov Unique Entity Identifier (12-char, case-insensitive).                                                                                                                                                                                              |
| `recipient` | Fuzzy (case-insensitive substring) recipient-name match — no id needed.                                                                                                                                                                                      |
| `limit`     | Award-timeline rows (default 100, max 500). Summary/rollups aggregate across **all** matching awards regardless of this cap.                                                                                                                                 |

```bash theme={null}
# Federal awards for a defense prime, by name (no id needed)
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
  "https://gdeltcloud.com/api/v2/gov/awards?recipient=Lockheed&limit=25"

# By resolved spine entity id (from /api/v2/search)
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
  "https://gdeltcloud.com/api/v2/gov/awards?entity=e_7e9bc31057830fbf"
```

<Note>
  The federal-awards surface is also on the **MCP server** as the `gov` category tool
  `gov_awards` (progressive discovery) — see [MCP → GDELT Cloud tools](/mcp/tools/gdelt-cloud),
  inheriting the same `can_use_gov` gate. Federal award data is US public domain
  ([USAspending.gov](https://www.usaspending.gov/)).
</Note>

## Foreign Agents (FARA)

`GET /api/v2/gov/fara` — the US foreign-influence graph. DOJ FARA registrations link a US
registrant (a law / lobbying / PR firm) to the **foreign principal** it represents, both
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`.

The differentiator is the **sanctions cross**: `sanctioned_only=true` returns only links whose
foreign principal is on one of our screening lists (OFAC SDN, BIS Entity List, DoD 1260H, OFAC
CMIC, UK) — with the specific `fp_sanction_lists` + `fp_sanction_programs` — so you see *US firms
registered as agents for a **sanctioned** entity*, not merely for an adversary country.

| Param               | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `entity`            | Resolved spine entity id — matches the registrant OR the foreign principal. |
| `registrant`        | Fuzzy US-registrant name (e.g. `Hogan Lovells`).                            |
| `foreign_principal` | Fuzzy foreign-principal name (e.g. `Huawei`).                               |
| `country`           | Country/location represented, as published (upper-case).                    |
| `adversary_only`    | `true` → adversary-government links only (RU/CN/IR/KP/…).                   |
| `sanctioned_only`   | `true` → the foreign principal is on a sanctions/restricted list.           |
| `active_only`       | `true` → still-active registrations only.                                   |
| `limit`             | Link rows (default 100, max 500).                                           |

```bash theme={null}
# US firms registered as agents for a SANCTIONED entity (OFAC/BIS/1260H)
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
  "https://gdeltcloud.com/api/v2/gov/fara?sanctioned_only=true&limit=25"

# Who represents Huawei
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
  "https://gdeltcloud.com/api/v2/gov/fara?foreign_principal=Huawei"
```

<Note>
  Also on the **MCP server** as `gov_fara` (the `gov` category). FARA is US public domain
  ([DOJ NSD FARA eFile](https://efile.fara.gov/)); one row per (US registrant, foreign principal) link.
</Note>

## Regulatory enforcement — in development

An **EPA ECHO enforcement** surface (facility-level violations, penalties, and non-compliance
for an operator, geo-matched to the [facilities directory](/api-reference/facilities)) is in
active development and available to admins in preview. It isn't yet exposed for general use:
attributing enforcement to the right operator at breadth requires geo-confirmation against the
operator's mapped facilities, which we're expanding before we serve it. It will land here once
that precision bar is met — so an operator search returns enforcement that is provably its own,
not a name-match.