# FRED Economic Series Data Export (`automation-lab/fred-economic-series-data-export`) Actor

Export normalized dates, values, source URLs, and retrieval timestamps for selected FRED economic series through the anonymous public CSV surface.

- **URL**: https://apify.com/automation-lab/fred-economic-series-data-export.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.72 / 1,000 observation exporteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## FRED Economic Series Data Export

Export selected **FRED economic data** series as normalized, analysis-ready observation rows without supplying a FRED API key.

Choose real series IDs such as `GDP`, `CPIAUCSL`, or `UNRATE`, apply an optional date window, and receive one dataset row per observation with the series ID, date, numeric value, exact source URL, and retrieval timestamp.

### What does this Actor do?

FRED Economic Series Data Export downloads the anonymous public CSV representation published by the Federal Reserve Bank of St. Louis.

It:

- accepts up to 100 selected FRED series IDs;
- fetches each series independently;
- applies optional start and end dates;
- converts numeric values to JSON numbers;
- represents FRED missing values as `null`;
- optionally excludes missing observations;
- caps total output with `maxItems`;
- preserves source and retrieval provenance;
- requires no FRED API key, account, cookies, browser, or proxy.

The default dataset contains normalized long-form rows that work well in spreadsheets, notebooks, databases, and dashboard refresh jobs.

### Who is this FRED economic data exporter for?

This Actor is useful for:

- economists refreshing a defined indicator set;
- analysts preparing macroeconomic reports;
- data engineers loading time series into a warehouse;
- finance teams maintaining dashboard inputs;
- researchers creating reproducible observation extracts;
- developers who want FRED CSV data through the Apify API;
- automation teams scheduling recurring snapshots.

Use it when you already know the FRED IDs you need. It does not search the FRED catalog or provide credentialed API-only metadata.

### Why use it?

The product focuses on a narrow recurring job: refresh selected public series and normalize their observations.

Compared with handling CSV downloads manually, it provides:

- one consistent JSON record shape across series;
- built-in date-window validation;
- deduplication of repeated input IDs;
- a total output safety limit;
- bounded transient retries;
- Apify scheduling, webhooks, integrations, datasets, and API access;
- explicit provenance on every row.

Each series uses its own CSV request. That avoids the ZIP response generated by FRED's multi-series download and makes partial pipeline diagnosis straightforward.

### What data is extracted?

| Field | Type | Meaning |
| --- | --- | --- |
| `seriesId` | string | Uppercase FRED series identifier |
| `observationDate` | date string | Observation date supplied by FRED |
| `value` | number or null | Numeric value, or null for a missing FRED observation |
| `sourceUrl` | URL | Exact CSV URL, including date filters |
| `retrievedAt` | ISO timestamp | Time the source response was retrieved |

Rows are ordered by the selected series order and then by the order in FRED's CSV response.

### Getting started

1. Open the Actor input page.
2. Enter one or more known FRED series IDs.
3. Optionally set `startDate` and `endDate`.
4. Choose whether missing values should remain in the dataset.
5. Set a suitable `maxItems` cap.
6. Click **Start**.
7. Open the default dataset to preview or export JSON, CSV, Excel, XML, or RSS.

A small first run can use:

```json
{
  "seriesIds": ["GDP"],
  "startDate": "2020-01-01",
  "maxItems": 30
}
```

### Input parameters

#### `seriesIds`

Required array of one to 100 IDs. IDs are trimmed, normalized to uppercase, and deduplicated.

Examples:

- `GDP` — Gross Domestic Product;
- `CPIAUCSL` — Consumer Price Index for All Urban Consumers;
- `UNRATE` — Civilian Unemployment Rate;
- `FEDFUNDS` — Effective Federal Funds Rate.

#### `startDate`

Optional inclusive start date in `YYYY-MM-DD` format. It is sent to FRED as `cosd`.

#### `endDate`

Optional inclusive end date in `YYYY-MM-DD` format. It is sent to FRED as `coed`.

The start date must not be later than the end date.

#### `includeMissingValues`

Defaults to `true`. Set it to `false` to omit rows whose CSV value is blank or `.`.

#### `maxItems`

Maximum total rows across every series. The allowed range is 1 to 100,000 and the default is 20 to keep first runs small.

The Actor stops before fetching another series after the cap is reached and truncates the current accepted batch at the cap.

### Output example

A real GDP run produces records shaped like:

```json
{
  "seriesId": "GDP",
  "observationDate": "2020-01-01",
  "value": 21751.238,
  "sourceUrl": "https://fred.stlouisfed.org/graph/fredgraph.csv?id=GDP&cosd=2020-01-01",
  "retrievedAt": "2026-09-13T14:06:27.587Z"
}
```

`retrievedAt` changes on every source response. FRED may revise historical observations, so a later run can legitimately return a changed value for the same series and date.

### How much does it cost to export FRED observations?

Pricing is pay per event. A run has a one-time start event and an item event for each observation saved to the default dataset.

The current configuration uses a $0.001 start event and a BRONZE item rate of $0.0012. Estimate a run by adding the start price to the item rate multiplied by the number of saved observations.

For example, a 25-row run has one start charge plus 25 item charges; a 100-row run has one start charge plus 100 item charges. Higher Apify tiers use the decreasing item rates declared on the Actor pricing tab.

Your Apify plan tier determines the exact item price. No item fee applies to rejected rows or missing rows that are filtered out. Platform compute and included usage follow Apify's normal account rules.

### Scheduling recurring macro reports

Create an Apify Task with your stable series list and a recent `startDate`.

Then:

1. schedule it daily, weekly, or monthly;
2. connect a webhook or integration;
3. export the new dataset;
4. upsert records by `seriesId` plus `observationDate`;
5. compare current values with your prior snapshot.

The Actor itself does not maintain historical diffs or send alerts. Apify schedules and downstream tools provide that workflow.

### Spreadsheet and data-pipeline integration

The default dataset can be downloaded in CSV or Excel format from Apify Console.

For a warehouse load:

- treat `seriesId` and `observationDate` as the natural observation key;
- store `retrievedAt` as the extraction timestamp;
- retain `sourceUrl` for lineage;
- allow `value` to be nullable;
- choose an upsert or append strategy based on whether revisions matter.

For Google Sheets, use the Apify integration or retrieve dataset items after the run succeeds.

### Run through the Apify API with cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~fred-economic-series-data-export/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seriesIds": ["GDP", "CPIAUCSL", "UNRATE"],
    "startDate": "2024-01-01",
    "includeMissingValues": false,
    "maxItems": 100
  }'
```

Keep tokens in environment variables or a secret manager rather than source code.

### JavaScript API example

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/fred-economic-series-data-export').call({
  seriesIds: ['GDP', 'CPIAUCSL', 'UNRATE'],
  startDate: '2024-01-01',
  maxItems: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/fred-economic-series-data-export").call(
    run_input={
        "seriesIds": ["GDP", "CPIAUCSL"],
        "startDate": "2023-01-01",
        "endDate": "2024-12-31",
        "maxItems": 100,
    }
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI assistants

Add this Actor to Claude Code through Apify MCP:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/fred-economic-series-data-export"
```

#### Claude Desktop, Cursor, and VS Code setup

Claude Desktop, Cursor, VS Code, and other MCP-capable clients can use:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/fred-economic-series-data-export"
    }
  }
}
```

Example prompts:

- “Export GDP observations since 2020 with the FRED series exporter.”
- “Fetch CPIAUCSL and UNRATE for 2024 and return at most 50 rows.”
- “Run my recurring macro dashboard input and summarize the latest observations.”

### Reliability and retry behavior

Each selected series receives one direct request to FRED's public CSV endpoint.

The Actor:

- uses a 30-second request timeout;
- retries transient network errors, HTTP 429, and server errors up to three times;
- uses short exponential backoff;
- does not blindly retry deterministic client errors;
- validates the response content type and expected CSV columns;
- fails the run if a selected series cannot be fetched correctly.

There is no automatic residential proxy or browser fallback.

### Limits

- Series IDs must already be known; there is no catalog search.
- FRED's public CSV surface does not provide the richer metadata available through its credentialed API.
- Values are returned as published, without frequency aggregation, unit transformation, seasonal adjustment, or derived percent-change calculations.
- `maxItems` applies across all series, so an early long series can consume the cap.
- A FRED source outage or format change can fail a run.
- Historical values may be revised by the source.
- The Actor supports at most 100 unique IDs and 100,000 output rows per run.

### Troubleshooting

#### “Invalid FRED series ID”

Remove spaces or URL fragments. Supply the identifier itself, for example `GDP`, not a FRED page URL.

#### No rows in my date range

Confirm that the series existed and published observations during the selected dates. Try removing the date window in a small capped run.

#### The run stops at `maxItems`

Increase the cap or split series into separate Tasks. The cap is global, not per series.

#### A value is null

FRED uses blank values or `.` for missing observations. Keep them for time-grid completeness or set `includeMissingValues` to `false`.

#### A run fails after retries

Inspect the log for the series ID and HTTP status. Retry later if FRED was unavailable; fix the ID if the error is deterministic.

### Legality and responsible use

This Actor accesses an anonymous public data export. Follow FRED's terms, attribution guidance, and any restrictions that apply to individual underlying series.

Do not imply that Automation Lab or this Actor is affiliated with, endorsed by, or operated by the Federal Reserve Bank of St. Louis.

Dataset consumers remain responsible for:

- validating fitness for their analysis;
- preserving source attribution;
- handling revisions and missing values;
- complying with applicable laws, licenses, and organizational policies;
- avoiding unsupported financial or policy conclusions.

### FAQ

#### Does it require a FRED API key?

No. It uses the public `fredgraph.csv` download surface.

#### Can it search for series?

No. Enter known IDs. This keeps the no-key contract predictable.

#### Can it fetch multiple series?

Yes, up to 100 IDs. Each is downloaded separately and normalized into one default dataset.

#### Does it transform units or frequency?

No. Values are preserved from the selected public export.

#### Can I schedule it?

Yes. Save the input as an Apify Task and attach a schedule.

#### How do I detect revisions?

Compare records across runs by `seriesId` and `observationDate`, using `retrievedAt` to identify each extraction.

#### Are missing values charged?

A null observation incurs the normal item price only when you choose to include it and it is saved. Set `includeMissingValues` to `false` to omit it.

### Related Automation Lab Actors

This Actor is intentionally standalone in the current portfolio. The retired credentialed FRED scraper is not offered as a related public product, and no other Automation Lab Actor currently provides a closer supported continuation of this exact workflow.

# Actor input Schema

## `seriesIds` (type: `array`):

One or more FRED series IDs, such as GDP, CPIAUCSL, or UNRATE.

## `startDate` (type: `string`):

Optional first observation date in YYYY-MM-DD format.

## `endDate` (type: `string`):

Optional last observation date in YYYY-MM-DD format.

## `includeMissingValues` (type: `boolean`):

Keep observations represented by a null value in FRED's CSV export.

## `maxItems` (type: `integer`):

Maximum total observation records saved across all selected series.

## Actor input object example

```json
{
  "seriesIds": [
    "GDP",
    "CPIAUCSL",
    "UNRATE"
  ],
  "startDate": "2020-01-01",
  "includeMissingValues": true,
  "maxItems": 20
}
```

# Actor output Schema

## `overview` (type: `string`):

Default dataset containing one normalized row per FRED series observation.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "seriesIds": [
        "GDP",
        "CPIAUCSL",
        "UNRATE"
    ],
    "startDate": "2020-01-01"
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/fred-economic-series-data-export").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "seriesIds": [
        "GDP",
        "CPIAUCSL",
        "UNRATE",
    ],
    "startDate": "2020-01-01",
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/fred-economic-series-data-export").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "seriesIds": [
    "GDP",
    "CPIAUCSL",
    "UNRATE"
  ],
  "startDate": "2020-01-01"
}' |
apify call automation-lab/fred-economic-series-data-export --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/fred-economic-series-data-export"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QmmPLW3DIgcBdHY6J/builds/Gb8kF3EA4XiwT0giV/openapi.json