<!-- Agent Datasets docs · Federal spending REST endpoints · canonical: https://www.agentdatasets.com/docs/rest/gov · rendered from https://www.agentdatasets.com -->

# Federal spending REST endpoints

US federal award recipients and obligation aggregates from USAspending — recipient registry, fiscal-year obligation trends, and top awarding agencies.

2 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients.

## GET /v1/gov/recipients/awards

Recipient Awards

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| recipient | query | `string` | yes | — | — | Exact recipient_id, UEI, or unique canonical recipient name |
| fiscal_years | query | `integer` | no | 5 | min 1, max 20 | Fiscal-year rows to return, newest first |
| cursor | query | `string \| null` | no | — | — | Opaque pagination.next_cursor from the prior response |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/gov/recipients/awards?recipient=RECIPIENT"
```

### Response

`200` Successful Response — `RecipientAwardsResult`.

- `data` `RecipientAwardsData` (required)
  - `recipient_id` `string` (required)
  - `name` `string` (required)
  - `uei` `string | null` (required)
  - `duns` `string | null` (required)
  - `recipient_level` `string` (required)
  - `parent_uei` `string | null` (required)
  - `parent_name` `string | null` (required)
  - `units` `"USD"`
  - `currency` `"USD"`
  - `period_type` `"fiscal_year"`
  - `amount_basis` `"transaction-level obligations"`
  - `source_notes` `string`
  - `fiscal_years` `array<RecipientFiscalYearAward>` (required)
    - `fiscal_year` `integer` (required)
    - `total_obligations` `string` (required)
    - `contract_obligations` `string` (required)
    - `direct_obligations` `string` (required)
    - `grant_obligations` `string` (required)
    - `idv_obligations` `string` (required)
    - `loan_obligations` `string` (required)
    - `other_obligations` `string` (required)
    - `top_agencies` `array<TopAgency>` (required)
      - `name` `string` (required)
      - `code` `string | null` (required)
      - `amount` `string` (required)
    - `as_of` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/gov/recipients/search

Recipients Search

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| query | query | `string` | yes | — | — | Recipient name, USAspending recipient_id, or UEI |
| limit | query | `integer` | no | 10 | min 1, max 50 | Maximum ranked recipient matches |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/gov/recipients/search?query=QUERY"
```

### Response

`200` Successful Response — `RecipientSearchResult`.

- `data` `RecipientSearchData` (required)
  - `query` `string` (required)
  - `matches` `array<RecipientMatch>` (required)
    - `recipient_id` `string` (required)
    - `name` `string` (required)
    - `uei` `string | null` (required)
    - `duns` `string | null` (required)
    - `recipient_level` `string` (required)
    - `parent_uei` `string | null` (required)
    - `parent_name` `string | null` (required)
    - `score` `integer` (required)
    - `match_reason` `string` (required)
    - `as_of` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json