# 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-usaspending-gov-api-c2bbf051/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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/parse-usaspending-gov-api-c2bbf051/get_award_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-usaspending-gov-api-c2bbf051/list_agencies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-usaspending-gov-api-c2bbf051/search_awards \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-usaspending-gov-api-c2bbf051/search_recipients \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-usaspending-gov-api-c2bbf051/search_spending_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-usaspending-gov-api-c2bbf051/search_subawards \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<object>","keywords":"<string>","limit":"<integer>","page":"<integer>"}'
```