# USAspending — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access data from usaspending.gov.

**Category:** Government & Public Data | **Website:** [usaspending.gov/](https://usaspending.gov/) | **Docs:** [parse.bot/marketplace/c2bbf051-599a-43fd-90f0-0c50d060146d/usaspending-gov-api](https://parse.bot/marketplace/c2bbf051-599a-43fd-90f0-0c50d060146d/usaspending-gov-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/usaspending/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get award details

Get comprehensive details for a specific award including recipient info, contract data, period of performance, and funding/awarding agency details. Returns the full award record from USASpending.gov given a generated_internal_id from search_awards results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `award_id` | string | Yes | Generated internal award ID from search_awards results[*].generated_internal_id (e.g. 'CONT_AWD_W91ZLK23F0033_9700_W52P1J20D0042_9700'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/usaspending/get-award-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"award_id":"<string>"}'
```

### List agencies

List all federal toptier agencies with budget authority amounts for the current active fiscal year and quarter. Returns agencies sorted by the specified field. Each agency includes budget_authority_amount, percentage_of_total_budget_authority, and agency_slug for further lookups.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `order` | string | No | Sort order: 'asc' for ascending, 'desc' for descending. |
| `sort` | string | No | Field to sort results by. Accepted values: 'percentage_of_total_budget_authority', 'agency_name', 'budget_authority_amount', 'obligated_amount', 'outlay_amount'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/usaspending/list-agencies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"order":"<string>","sort":"<string>"}'
```

### Search awards

Search for government awards with advanced filtering. Returns paginated results of contracts and other award types. Supports keyword search and complex filter objects including time_period, award_type_codes, and agencies. If award_type_codes is not specified in filters, defaults to contracts (A, B, C, D).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filters` | object | No | JSON object of filters including keywords, time_period, award_type_codes, agencies, etc. If award_type_codes is not specified, defaults to contracts (A, B, C, D). |
| `keywords` | string | No | Comma-separated search keywords to filter awards by (e.g. 'Salesforce' or 'Microsoft,Amazon'). Applied as keyword filter if no keywords are present in the filters object. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/usaspending/search-awards \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<object>","keywords":"<string>"}'
```

### Search recipients

Search for award recipients by name via autocomplete. Returns matching recipient names with optional UEI and DUNS identifiers. Useful for finding the exact recipient name to use in award filters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `search_text` | string | No | Recipient name search text (e.g. 'Microsoft'). Returns all recipients if empty. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/usaspending/search-recipients \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"search_text":"<string>"}'
```

### Search spending by category

Search for spending grouped by a category such as awarding agency, recipient, or geographic area. A default time_period filter covering the past year is applied if none is provided in filters. Returns the top results by amount for the chosen category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category to group spending by. Accepted values: 'awarding_agency', 'awarding_subagency', 'funding_agency', 'funding_subagency', 'recipient_duns', 'recipient_parent_duns', 'county', 'district', 'state_territory', 'country', 'federal_account', 'cfda', 'naics', 'psc'. |
| `filters` | object | No | JSON object of filters including time_period, keywords, award_type_codes, etc. If time_period is not specified, defaults to the past year from today. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/usaspending/search-spending-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","filters":"<object>"}'
```

### Search subawards

Search for government subawards with advanced filtering. Returns paginated results of subcontracts and subgrants under prime awards. Supports keyword search and complex filter objects including time_period, award_type_codes, prime_award_id, prime_recipient_name, subawardee_name, and awarding_agency. If award_type_codes is not specified in filters, defaults to contracts (A, B, C, D).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filters` | object | No | JSON object of filters including keywords, time_period, award_type_codes, prime_award_id, prime_recipient_name, subawardee_name, awarding_agency. If award_type_codes is not specified, defaults to contracts (A, B, C, D). |
| `keywords` | string | No | Comma-separated search keywords to filter subawards by (e.g. 'Salesforce' or 'Microsoft,Amazon'). Applied as keyword filter if no keywords are present in the filters object. |
| `limit` | integer | No | Number of results per page (max 100). |
| `page` | integer | No | Page number for paginated results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/usaspending/search-subawards \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<object>","keywords":"<string>","limit":"<integer>","page":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.