# FRED Economic Data Search (`ryanclinton/fred-economic-data`) Actor

FRED Economic Data Search is an Apify actor that connects to the Federal Reserve Economic Data (FRED) API to search, retrieve, and download US economic time series data. With access to over 840,000 data series maintained by the Federal Reserve Bank of St.

- **URL**: https://apify.com/ryanclinton/fred-economic-data.md
- **Developed by:** [Ryan Clinton](https://apify.com/ryanclinton) (community)
- **Categories:** AI, Developer tools
- **Features:** Limited permissions
- **Stats:** 9 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 data fetcheds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## FRED Economic Data Search

FRED Economic Data Search is an Apify actor that connects to the Federal Reserve Economic Data (FRED) API to search, retrieve, and download US economic time series data. With access to over 840,000 data series maintained by the Federal Reserve Bank of St. Louis, this actor delivers GDP figures, unemployment rates, inflation metrics, interest rates, housing data, and hundreds of thousands of other indicators in structured JSON format -- ready for analysis, dashboards, or automated pipelines.

***

### Why use FRED Economic Data Search?

Accessing FRED data programmatically requires handling API authentication, pagination, missing value filtering, and response normalization. This actor eliminates that development overhead. You configure a query through a simple web form or JSON input, run the actor on Apify, and receive clean, structured data in seconds.

Running on Apify gives you scheduled recurring data pulls, cloud-based execution with no infrastructure to maintain, built-in integrations with Google Sheets and Slack, and dataset export in JSON, CSV, or Excel. The actor is purpose-built for economists, financial analysts, data scientists, journalists, and researchers who need reliable, automated access to US economic statistics.

***

### Key features

- **840,000+ economic time series** searchable by keyword, ranked by popularity
- **Three operating modes** -- search for series discovery, observations for time series data, series for metadata lookup
- **Date range filtering** with configurable start and end dates on observation data
- **Frequency aggregation** to convert data to daily, weekly, biweekly, monthly, quarterly, semi-annual, or annual intervals
- **Automatic missing data filtering** that removes FRED's "." placeholder values from results
- **Pagination support** with configurable results up to 1,000 series per search
- **Rich metadata** including units, seasonal adjustment, popularity scores, and descriptive notes
- **Dry-run mode** that outputs setup instructions when no API key is provided
- **Clean JSON output** exportable to CSV, Excel, Google Sheets, or consumable via API

***

### How to use FRED Economic Data Search

1. **Get a free FRED API key.** Visit <https://fred.stlouisfed.org/docs/api/api_key.html>, create a free account, and request an API key from your account settings.
2. **Open the actor** on the [Apify Console](https://apify.com/ryanclinton/fred-economic-data) or call it via the API.
3. **Choose your mode.** Select `search` to discover data series by keyword, `observations` to download actual data values, or `series` to retrieve metadata about known series IDs.
4. **Configure your query.** For search mode, enter keywords like "GDP" or "unemployment". For observations or series mode, provide FRED series IDs such as `GDP`, `UNRATE`, `CPIAUCSL`, or `FEDFUNDS`.
5. **Set optional filters.** Narrow observation data with start/end dates and choose a frequency aggregation level.
6. **Run the actor** and download results from the dataset in JSON, CSV, or Excel format.

***

### Input parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `apiKey` | String | Yes | -- | Free FRED API key from [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html). |
| `mode` | String | No | `search` | Operating mode: `search`, `observations`, or `series`. |
| `searchText` | String | Conditional | -- | Keywords to search for economic series. Required when mode is `search`. |
| `seriesIds` | String\[] | Conditional | -- | One or more FRED series IDs. Required for `observations` and `series` modes. |
| `startDate` | String | No | -- | Start date for observations in `YYYY-MM-DD` format. |
| `endDate` | String | No | -- | End date for observations in `YYYY-MM-DD` format. |
| `frequency` | String | No | -- | Aggregate to: `d` (daily), `w` (weekly), `bw` (biweekly), `m` (monthly), `q` (quarterly), `sa` (semi-annual), `a` (annual). |
| `maxResults` | Integer | No | 50 | Maximum series to return in search mode (1--1,000). |

#### Input example (search mode)

```json
{
    "apiKey": "your_fred_api_key_here",
    "mode": "search",
    "searchText": "GDP",
    "maxResults": 10
}
```

#### Input example (observations mode)

```json
{
    "apiKey": "your_fred_api_key_here",
    "mode": "observations",
    "seriesIds": ["UNRATE", "CPIAUCSL"],
    "startDate": "2023-01-01",
    "endDate": "2023-12-31",
    "frequency": "m",
    "maxResults": 50
}
```

#### Tips for best results

- **Search first, then fetch.** Use search mode to discover series IDs, then pass them to observations mode for actual data.
- **Use well-known series IDs** for common indicators: `GDP`, `UNRATE`, `CPIAUCSL`, `FEDFUNDS`, `DGS10`, `HOUST`, `SP500`, `DEXUSEU`.
- **Set date ranges** to avoid pulling decades of data when you only need recent values.
- **Use frequency aggregation** to reduce volume. Set frequency to `a` for annual summaries instead of downloading daily or monthly data.
- **Batch series IDs** in a single run. Observations and series modes accept multiple IDs, so you can fetch unemployment, GDP, and CPI together.
- **Schedule recurring runs** on Apify to build automated monitoring pipelines that track key economic indicators over time.

***

### Output

#### Output example (search mode)

```json
{
    "seriesId": "GDP",
    "title": "Gross Domestic Product",
    "frequency": "Quarterly",
    "units": "Billions of Dollars",
    "seasonalAdjustment": "Seasonally Adjusted Annual Rate",
    "observationStart": "1947-01-01",
    "observationEnd": "2025-01-01",
    "lastUpdated": "2025-03-27 07:56:06-05",
    "popularity": 95,
    "notes": "BEA Account Code: A191RC. Gross domestic product (GDP), the featured measure of U.S. output, is the market value of the goods and services produced by labor and property located in the United States.",
    "extractedAt": "2025-04-15T14:30:00.000Z"
}
```

#### Output example (observations mode)

```json
{
    "seriesId": "UNRATE",
    "title": "Unemployment Rate",
    "date": "2023-06-01",
    "value": "3.6",
    "units": "Percent",
    "frequency": "Monthly"
}
```

#### Output fields

**Search and series mode:**

| Field | Type | Description |
|-------|------|-------------|
| `seriesId` | String | FRED series identifier (e.g., `GDP`, `UNRATE`). |
| `title` | String | Full descriptive name of the series. |
| `frequency` | String | Reporting frequency (e.g., "Quarterly", "Monthly"). |
| `units` | String | Measurement units (e.g., "Billions of Dollars", "Percent"). |
| `seasonalAdjustment` | String | Seasonal adjustment method applied. |
| `observationStart` | String | Earliest available observation date. |
| `observationEnd` | String | Most recent observation date. |
| `lastUpdated` | String | Timestamp of the last data update. |
| `popularity` | Number | FRED popularity ranking (0--100). |
| `notes` | String | Descriptive notes and methodology. |
| `extractedAt` | String | ISO 8601 timestamp of when the actor ran. |

**Observations mode:**

| Field | Type | Description |
|-------|------|-------------|
| `seriesId` | String | FRED series identifier. |
| `title` | String | Full descriptive name of the series. |
| `date` | String | Observation date in `YYYY-MM-DD` format. |
| `value` | String | Data value for the observation. |
| `units` | String | Measurement units. |
| `frequency` | String | Reporting frequency of the series. |

***

### Use cases

- **Economic research** -- download GDP, inflation, and employment data for academic papers, policy analysis, or forecasting models.
- **Financial analysis** -- track interest rates (`FEDFUNDS`, `DGS10`), treasury yields, and money supply (`M2SL`) for investment decision-making.
- **Automated dashboards** -- schedule daily or weekly runs to feed economic indicators into Google Sheets, Tableau, or Power BI.
- **Journalism and reporting** -- pull official economic statistics with full metadata and sourcing for data-driven stories.
- **Machine learning pipelines** -- collect historical time series data to train forecasting models on unemployment (`UNRATE`), housing starts (`HOUST`), or consumer prices (`CPIAUCSL`).
- **Cross-indicator comparison** -- batch-fetch multiple series in one run to compare GDP growth against inflation, employment, or trade balance trends.

#### Popular FRED series IDs

| Series ID | Description | Frequency |
|-----------|-------------|-----------|
| `GDP` | Gross Domestic Product | Quarterly |
| `UNRATE` | Unemployment Rate | Monthly |
| `CPIAUCSL` | Consumer Price Index (All Urban) | Monthly |
| `FEDFUNDS` | Federal Funds Effective Rate | Monthly |
| `DGS10` | 10-Year Treasury Constant Maturity | Daily |
| `HOUST` | Housing Starts | Monthly |
| `SP500` | S\&P 500 Index | Daily |
| `M2SL` | M2 Money Supply | Monthly |
| `DEXUSEU` | US/Euro Exchange Rate | Daily |
| `PAYEMS` | Total Nonfarm Payrolls | Monthly |

***

### API and integration

Use the [Apify API](https://docs.apify.com/api/v2) to run FRED Economic Data Search programmatically. The actor ID is `gz0VOFSLZkFwhqOS8`.

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("ryanclinton/fred-economic-data").call(run_input={
    "apiKey": "your_fred_api_key",
    "mode": "observations",
    "seriesIds": ["GDP", "UNRATE"],
    "startDate": "2020-01-01",
    "frequency": "q"
})

dataset = client.dataset(run["defaultDatasetId"])
for item in dataset.iterate_items():
    print(f"{item['seriesId']}: {item['date']} = {item['value']} {item['units']}")
```

#### JavaScript

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

const client = new ApifyClient({ token: "YOUR_APIFY_TOKEN" });

const run = await client.actor("ryanclinton/fred-economic-data").call({
    apiKey: "your_fred_api_key",
    mode: "search",
    searchText: "consumer price index",
    maxResults: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => console.log(`${item.seriesId}: ${item.title}`));
```

#### cURL

```bash
curl "https://api.apify.com/v2/acts/gz0VOFSLZkFwhqOS8/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -d '{
    "apiKey": "your_fred_api_key",
    "mode": "observations",
    "seriesIds": ["FEDFUNDS"],
    "startDate": "2024-01-01",
    "frequency": "m"
  }'
```

#### Integrations

- **Google Sheets** -- automatically push economic data to spreadsheets for dashboards and reporting.
- **Slack / Email** -- receive notifications when new data is available after a scheduled run.
- **Webhooks** -- trigger downstream workflows in Zapier, Make, or n8n when a run completes.
- **Apify API** -- consume results programmatically from any language or platform.

***

### How it works

```
                     FRED Economic Data Search
                     =========================

[Input Config]         [FRED API]              [Apify Dataset]
      |                     |                        |
      v                     v                        v
 +---------+     +-------------------+     +------------------+
 | apiKey   |---->| api.stlouisfed.   |---->| Clean JSON       |
 | mode     |     | org/fred          |     | output with      |
 | seriesIds|     |                   |     | metadata         |
 | dates    |     | /series/search    |     |                  |
 | frequency|     | /series           |     | Export: JSON,    |
 | maxResult|     | /series/observ.   |     | CSV, Excel       |
 +---------+     +-------------------+     +------------------+
      |                     |                        |
      v                     v                        v
  Mode routing       Pagination &            Push to dataset
  & validation       missing value           via Actor.pushData
                     filtering (".")
```

1. The actor reads input configuration and validates required fields based on the selected mode.
2. For **search** mode, it queries the FRED `/series/search` endpoint with keywords, paginating through results ordered by popularity in descending order. Each page is processed until the `maxResults` limit is reached or no more results are available.
3. For **observations** mode, the actor first fetches `/series` metadata for each series ID to obtain the title, units, and frequency. It then calls `/series/observations` with optional date range and frequency parameters. FRED represents missing data points with a "." string value -- the actor automatically filters these out so your dataset contains only valid numeric observations.
4. For **series** mode, it retrieves `/series` metadata for each provided series ID, returning the same structured output as search mode.
5. All results are normalized into clean JSON objects and pushed to the Apify dataset, where they can be exported or accessed via the API.

***

### Performance and cost

| Scenario | Memory | Duration | Est. cost |
|----------|--------|----------|-----------|
| Search for 50 series | 128 MB | ~5 sec | ~$0.001 |
| Observations for 1 series (1 year, monthly) | 128 MB | ~5 sec | ~$0.001 |
| Observations for 5 series (10 years, monthly) | 256 MB | ~15 sec | ~$0.003 |
| Observations for 10 series (full history) | 256 MB | ~30 sec | ~$0.005 |
| Series metadata for 20 IDs | 128 MB | ~10 sec | ~$0.002 |

The FRED API key is completely free with no usage fees from the Federal Reserve Bank of St. Louis. Apify platform costs are minimal -- most use cases fit comfortably within the free tier ($5/month in credits). Even heavy users running multiple daily scheduled pulls across dozens of series will typically spend only a few cents per month.

***

### Limitations

- **API key required.** A free FRED API key must be obtained from [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html). Without it, the actor runs in dry-run mode only.
- **FRED API rate limits.** The FRED API does not publish strict rate limits, but excessive requests may be throttled. The actor's pagination handles this gracefully for normal workloads.
- **Search limited to 1,000 results.** The `maxResults` parameter caps at 1,000 series per search query.
- **Values returned as strings.** Observation values are returned as strings (matching FRED's API format) and may need numeric conversion for calculations.
- **US-focused data.** While FRED includes some international series, the primary coverage is US economic indicators.
- **No real-time streaming.** The actor fetches a snapshot of data per run. For continuous monitoring, schedule recurring runs on Apify.

***

### Responsible use

This actor retrieves data from the FRED API, a public service provided by the Federal Reserve Bank of St. Louis. Please use it responsibly:

- Comply with the [FRED API Terms of Use](https://fred.stlouisfed.org/docs/api/terms_of_use.html) when using retrieved data.
- Attribute data to its original source (Federal Reserve Bank of St. Louis, FRED) in any publications or reports.
- Avoid excessive request volumes that could strain the FRED API infrastructure.
- Do not use this actor to redistribute raw FRED data as a competing data service.

***

### FAQ

**Do I need a FRED API key?**
Yes. The actor requires a free API key from the Federal Reserve Bank of St. Louis. Register at [fred.stlouisfed.org/docs/api/api_key.html](https://fred.stlouisfed.org/docs/api/api_key.html). Registration is free and takes only a few minutes.

**What happens if I run without an API key?**
The actor runs in dry-run mode and outputs step-by-step instructions for obtaining a free API key. No economic data is returned.

**What economic data is available through FRED?**
FRED contains over 840,000 time series from 114 sources, including GDP, employment, inflation, interest rates, exchange rates, housing data, industrial production, consumer sentiment, money supply, government debt, and trade balances. Data primarily covers the United States, with some international series.

**How far back does the historical data go?**
It depends on the series. Some series like GDP go back to 1947. Others may have shorter histories. The `observationStart` field in search and series results shows the earliest available data point for each series.

**Can I get daily or real-time data?**
Yes. Some FRED series are updated daily, such as `DFF` (daily Federal Funds effective rate) and `DGS10` (10-Year Treasury yield). Use observations mode with the appropriate series ID to fetch the latest values.

**How do I find the right series ID?**
Use search mode with descriptive keywords. For example, searching "consumer price index" returns relevant series ranked by popularity. The top result is usually the most commonly used version of that indicator. Use the returned `seriesId` value in subsequent observations or series mode runs.

**What is frequency aggregation and when should I use it?**
Frequency aggregation converts data from a higher frequency to a lower one. For example, if a series reports daily values but you only need monthly averages, set frequency to `m`. The FRED API handles the aggregation server-side, so you receive pre-computed values at your chosen interval. This is useful for reducing data volume, aligning multiple series to the same frequency for comparison, or simplifying analysis when granular data is not needed.

**Can I use this actor on a schedule?**
Yes. Apify supports cron-based scheduling for any actor. You can configure the actor to run daily, weekly, or monthly to automatically pull the latest economic data into your dataset. Combined with integrations like Google Sheets or webhooks, this creates a fully automated economic data monitoring pipeline.

***

### Related actors

| Actor | Description |
|-------|-------------|
| [BLS US Economic Data Search](https://apify.com/ryanclinton/bls-economic-data) | Bureau of Labor Statistics data including employment, wages, price indices, and productivity metrics. |
| [World Bank Development Indicators](https://apify.com/ryanclinton/world-bank-indicators) | Global development indicators for cross-country economic comparisons. |
| [OECD Economic Statistics](https://apify.com/ryanclinton/oecd-statistics-search) | International economic data from OECD statistical datasets. |
| [IMF Economic Data](https://apify.com/ryanclinton/imf-economic-data) | International Monetary Fund economic indicators and forecasts. |
| [Finnhub Stock Market Data](https://apify.com/ryanclinton/finnhub-stock-data) | Real-time and historical stock market data to complement economic indicators. |
| [Currency Exchange Rate Tracker](https://apify.com/ryanclinton/exchange-rate-tracker) | Live and historical currency exchange rates for international economic analysis. |

# Actor input Schema

## `apiKey` (type: `string`):

Free API key from FRED (register at https://fred.stlouisfed.org/docs/api/api_key.html)

## `mode` (type: `string`):

What to retrieve

## `searchText` (type: `string`):

Keywords to search for economic series (for search mode)

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

FRED series IDs for observations/series mode (e.g. GDP, UNRATE, CPIAUCSL, FEDFUNDS)

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

Start date for observations (YYYY-MM-DD)

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

End date for observations (YYYY-MM-DD)

## `frequency` (type: `string`):

Aggregate observations to this frequency

## `maxResults` (type: `integer`):

Maximum number of series to return in search mode

## Actor input object example

```json
{
  "mode": "search",
  "searchText": "GDP",
  "maxResults": 50
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "searchText": "GDP"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ryanclinton/fred-economic-data").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 = { "searchText": "GDP" }

# Run the Actor and wait for it to finish
run = client.actor("ryanclinton/fred-economic-data").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 '{
  "searchText": "GDP"
}' |
apify call ryanclinton/fred-economic-data --silent --output-dataset

```

## MCP server setup

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

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/gz0VOFSLZkFwhqOS8/builds/BzBy7SfgnCPIhvaSF/openapi.json