# FRED — 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 fred.stlouisfed.org.

**Category:** Finance & Markets | **Website:** [fred.stlouisfed.org/](https://fred.stlouisfed.org/) | **Docs:** [parse.bot/marketplace/86aad3a9-0339-44de-9c99-ee1f97abc9c9/fred-stlouisfed-org-api](https://parse.bot/marketplace/86aad3a9-0339-44de-9c99-ee1f97abc9c9/fred-stlouisfed-org-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/fred/`
**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 categories

Get all top-level FRED categories. Returns a flat array of category objects with their numeric ID and name. These IDs can be passed to get_category for subcategories and series.

**Estimated cost:** Metered

_No parameters required._

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

### Get category

Get details for a specific category, including its subcategories and featured series. The category_id comes from get_categories or from subcategories in a previous get_category call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Numeric category ID (from get_categories or get_category subcategories) |

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

### Get collection

Retrieve a pre-defined collection of related series with their metadata. Available collections group popular series by economic topic. Each series includes its ID, title, last update date, and units.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `collection_type` | string | No | Collection type: 'gdp', 'inflation', 'employment', 'treasury', 'money', 'housing' |

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

### Get release calendar

Get the current week's economic data release calendar. Returns a list of scheduled releases for the current week with date, time, release name, and release ID.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/fred/get-release-calendar \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get release series

Get all series associated with a specific release. Returns the release_id and an array of series with their IDs and titles.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `release_id` | string | Yes | Release ID (from get_releases) |

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

### Get releases

Get a list of all FRED data releases with their IDs and names. Release IDs can be used with get_release_series to list associated series.

**Estimated cost:** Metered

_No parameters required._

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

### Get series

Retrieve metadata for an economic data series including title, frequency, units, source, and last updated date. Returns a single Series resource identified by its series_id.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `series_id` | string | Yes | Series ID (e.g. 'GDP', 'CPIAUCSL', 'UNRATE') |

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

### Get series observations

Retrieve time-series observations for a series. Returns date-value pairs as an array. Supports date range filtering and frequency aggregation. Each observation has a date and a numeric value (null when data is unavailable).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `end_date` | string | No | Ending date (YYYY-MM-DD) |
| `frequency` | string | No | Aggregation frequency: 'm' for monthly, 'q' for quarterly, 'a' for annual |
| `series_id` | string | Yes | Series ID (e.g. 'GDP', 'UNRATE') |
| `start_date` | string | No | Starting date (YYYY-MM-DD) |
| `transformation` | string | No | Transformation type: 'lin' for levels, 'chg' for change, 'pch' for percent change |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/fred/get-series-observations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"end_date":"<string>","frequency":"<string>","series_id":"<string>","start_date":"<string>","transformation":"<string>"}'
```

### Search series

Search for economic data series matching a query. Returns paginated results with series ID, title, metadata summary, and popularity score. Results are ordered by relevance.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Search keywords (e.g. 'inflation', 'unemployment rate') |

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

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