# FRED Economic Data Scraper (US Macro Time Series) (`scrapers_lat/fred-economic-data-scraper`) Actor

Pull US macro and finance time series from FRED (Federal Reserve Economic Data): unemployment, CPI, GDP, Fed Funds, Treasury yields, M2 and more. Get latest value, YoY change and recent points. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/scrapers\_lat/fred-economic-data-scraper.md
- **Developed by:** [Scrapers Lat](https://apify.com/scrapers_lat) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $9.46 / 1,000 series results

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 Data Scraper (US Macro Time Series)](https://scrapers.lat/banners/fred-economic-data-scraper.png)](https://console.apify.com/actors/VkZLpQvju5Hw6b4pD/input)

## FRED Economic Data Scraper (US Macro Time Series)

Here is one real result, with every field the actor returns:

```json
{
  "seriesId": "UNRATE",
  "title": "Unemployment Rate",
  "units": "Percent,Seasonally Adjusted",
  "frequency": "Monthly",
  "seasonalAdjustment": "Seasonally Adjusted",
  "lastUpdated": "Aug 7, 2026 8:31 AM CDT",
  "notes": "View data of the unemployment rate, or the number of people 16 and over actively searching for a job as a percentage of the total labor force. ...",
  "observationStart": "1948-01-01",
  "observationEnd": "2026-07-01",
  "observationCount": 943,
  "latestValue": 4.1,
  "latestDate": "2026-07-01",
  "previousValue": 4.2,
  "previousDate": "2026-06-01",
  "changeFromPrevious": -0.1,
  "pctChangeYoY": -4.65,
  "recentObservations": [
    { "date": "2026-04-01", "value": 4.3 },
    { "date": "2026-05-01", "value": 4.3 },
    { "date": "2026-06-01", "value": 4.2 },
    { "date": "2026-07-01", "value": 4.1 }
  ],
  "observations": "[ 943 dated points, oldest 1948-01-01 ... included only with the Full history add-on ]",
  "fredUrl": "https://fred.stlouisfed.org/series/UNRATE",
  "matchedQuery": "seriesIds",
  "aiTrend": "falling",
  "aiPlainEnglish": "The unemployment rate is decreasing.",
  "aiNotableChange": "The unemployment rate dropped from 4.4% to 4.1% over the last five months.",
  "aiDirection": "down",
  "source": "FRED (Federal Reserve Economic Data)",
  "observedAt": "2026-08-20T05:40:32.776Z",
  "error": null
}
```

The most complete FRED time-series scraper available. It returns every core field FRED exposes for a series (title, units, frequency, seasonal adjustment, last updated, notes and the full observation history), plus derived fields you would otherwise compute yourself (latest value and date, change from the previous point, year-over-year percent change and the recent observation window), and it takes either explicit series IDs or a plain keyword search so you can pull unemployment, CPI, GDP, the Fed Funds rate, Treasury yields, M2 and thousands of other US macro series in one run.

**[Input](https://apify.com/scrapers_lat/fred-economic-data-scraper/input-schema) · [Output](https://apify.com/scrapers_lat/fred-economic-data-scraper/output-schema) · [Pricing](https://apify.com/scrapers_lat/fred-economic-data-scraper/pricing) · [Examples](https://apify.com/scrapers_lat/fred-economic-data-scraper/examples)**

![Platform](https://img.shields.io/badge/platform-Apify-blue) ![Coverage](https://img.shields.io/badge/coverage-US%20macro%20%26%20finance-green) ![Output](https://img.shields.io/badge/output-JSON%20%7C%20CSV%20%7C%20Excel-orange) ![Billing](https://img.shields.io/badge/billing-pay%20per%20result-brightgreen)

### Table of contents

- [What it does](#what-it-does)
- [Quickstart](#quickstart)
- [Input reference](#input-reference)
- [Output reference](#output-reference)
- [Example output record](#example-output-record)
- [Run via API and CLI](#run-via-api-and-cli)
- [Fetch results](#fetch-results)
- [Billing and limits](#billing-and-limits)
- [FAQ and troubleshooting](#faq-and-troubleshooting)
- [More scrapers at scrapers.lat](#more-scrapers-at-scraperslat)

### What it does

Give it a list of FRED series IDs (for example `UNRATE`, `CPIAUCSL`, `GDP`, `FEDFUNDS`, `DGS10`, `M2SL`) and/or a keyword search, and it returns one clean record per series. Each record carries the series metadata, the latest value and date, the change from the previous point, the year-over-year percent change, and the most recent observation points. Two opt-in add-ons extend a record: the full historical observation array, and an AI-written plain-English read of where the series is heading.

- Resolve series by ID or by keyword search (one keyword can return several matching series).
- Latest value, previous value, change and year-over-year percent change computed for you.
- Configurable window of recent observation points inside each record.
- Optional full history (every point back to the series start) as an add-on.
- Optional AI economic summary (trend, notable recent change, direction) as an add-on.
- Set an observation start and end date to trim the range.

### Quickstart

Real input example:

```json
{
  "seriesIds": ["UNRATE", "CPIAUCSL", "FEDFUNDS"],
  "searchQuery": "10 year treasury yield",
  "recentObservations": 12,
  "includeFullHistory": false,
  "includeAiSummary": false,
  "maxResults": 10
}
```

Provide at least one of `seriesIds` or `searchQuery`. Both can be combined in a single run.

### Input reference

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `seriesIds` | array of strings | one of these two | FRED series IDs to fetch, one record each. | `["UNRATE","CPIAUCSL","GDP"]` |
| `searchQuery` | string | one of these two | Keyword resolved to matching FRED series. | `"inflation"` |
| `observationStart` | string | no | Earliest observation date (YYYY-MM-DD). Empty means full history. | `"2015-01-01"` |
| `observationEnd` | string | no | Latest observation date (YYYY-MM-DD). Empty means most recent. | `"2024-12-31"` |
| `recentObservations` | integer | no | How many latest points (date + value) to include per record. Default 12. | `12` |
| `includeFullHistory` | boolean | no | Add-on. Attach the full observation array per series. Default false. | `true` |
| `includeAiSummary` | boolean | no | Add-on. Add an AI plain-English read per series. Default false. | `true` |
| `maxResults` | integer | no | Max series per run. Free plans are capped at 10. | `10` |

### Output reference

| Name | Type | Description |
| --- | --- | --- |
| `seriesId` | string | FRED series ID. |
| `title` | string | Series title. |
| `units` | string | Units of measure. |
| `frequency` | string | Observation frequency (Daily, Weekly, Monthly, Quarterly, Annual). |
| `seasonalAdjustment` | string | Seasonal adjustment status. |
| `lastUpdated` | string | When FRED last updated the series. |
| `notes` | string | Series notes / description. |
| `observationStart` | string | First observation date in the returned range. |
| `observationEnd` | string | Last observation date in the returned range. |
| `observationCount` | integer | Number of observations in the range. |
| `latestValue` | number | Most recent non-missing value. |
| `latestDate` | string | Date of the most recent value. |
| `previousValue` | number | Prior non-missing value. |
| `previousDate` | string | Date of the prior value. |
| `changeFromPrevious` | number | Latest minus previous value. |
| `pctChangeYoY` | number | Year-over-year percent change. |
| `recentObservations` | array | Latest observation points, each `{date, value}`. |
| `observations` | array | Full history array (populated only with the Full history add-on). |
| `fredUrl` | string | FRED series page URL. |
| `matchedQuery` | string | Which input produced this series. |
| `aiTrend` | string | AI trend label (AI add-on). |
| `aiPlainEnglish` | string | AI one-sentence summary (AI add-on). |
| `aiNotableChange` | string | AI notable recent change (AI add-on). |
| `aiDirection` | string | AI direction up / down / stable (AI add-on). |
| `source` | string | Data source. |
| `observedAt` | string | When the record was scraped. |
| `error` | string | Error message for a skipped or unknown series, otherwise null. |

### Example output record

```json
{
  "seriesId": "CPIAUCSL",
  "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
  "units": "Index 1982-1984=100,Seasonally Adjusted",
  "frequency": "Monthly",
  "seasonalAdjustment": "Seasonally Adjusted",
  "lastUpdated": "Aug 12, 2026 9:10 AM CDT",
  "observationStart": "1947-01-01",
  "observationEnd": "2026-07-01",
  "observationCount": 955,
  "latestValue": 332.813,
  "latestDate": "2026-07-01",
  "pctChangeYoY": 3.3,
  "recentObservations": [
    { "date": "2026-06-01", "value": 331.9 },
    { "date": "2026-07-01", "value": 332.813 }
  ],
  "matchedQuery": "seriesIds",
  "source": "FRED (Federal Reserve Economic Data)",
  "error": null
}
```

### Run via API and CLI

Start a run with the Apify API:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~fred-economic-data-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seriesIds":["UNRATE","CPIAUCSL","FEDFUNDS"],"recentObservations":12}'
```

Or with the Apify CLI:

```bash
apify call scrapers_lat/fred-economic-data-scraper \
  --input '{"seriesIds":["UNRATE","DGS10"],"includeFullHistory":true}'
```

### Fetch results

```bash
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_TOKEN&clean=true"
```

Add `&format=csv` or `&format=xlsx` to download as CSV or Excel.

### Billing and limits

- Pay per result. The primary `result` event is charged once per series record returned.
- A one-time actor-start event is charged when a run begins.
- Add-ons are opt-in and charged only when they genuinely return data: `full_history` per series with a non-empty history, `ai_econ_summary` per series with a usable AI read.
- Add-ons are disabled for free Apify plans, and free plans are capped at 10 series per run.
- No charge on failure: an unknown or unavailable series is written as an error row and is never billed.
- A spend cap is honored. Once your configured maximum charge is reached, the actor stops emitting and charging further results.

### FAQ and troubleshooting

**Do I need a FRED account or API key?** No. Just provide series IDs or a keyword.

**How do I find series IDs?** Use the `searchQuery` field with a plain keyword, or take the ID from a FRED series page (for example `UNRATE`, `CPIAUCSL`, `GDP`, `FEDFUNDS`, `DGS10`, `M2SL`).

**Why is a value null?** FRED marks missing observations with a placeholder; those points are returned with a null value, and `latestValue` uses the most recent real number.

**How far back does history go?** To each series start (unemployment goes back to 1948, CPI to 1947, 10-year Treasury to 1962). Use `observationStart` and `observationEnd` to trim the range.

**Can one keyword return several series?** Yes. A search resolves to the top matching series IDs, up to `maxResults`.

### More scrapers at scrapers.lat

Building macro and finance datasets? Pair this with our World Bank, IMF, OECD, ECB, US Treasury and BLS scrapers for a complete cross-source economic dataset. Browse the full catalog at [scrapers.lat](https://scrapers.lat).

*This is an independent scraper and is not affiliated with, endorsed by, or sponsored by the Federal Reserve Bank of St. Louis or FRED.*

# Actor input Schema

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

One or more FRED series IDs to fetch, for example UNRATE (unemployment rate), CPIAUCSL (CPI), GDP, FEDFUNDS (Fed Funds rate), DGS10 (10-year Treasury), M2SL (money supply). One record is returned per series. At least one of Series IDs or Search Query is required.

## `searchQuery` (type: `string`):

A keyword to resolve to FRED series, for example "unemployment rate", "inflation", "mortgage rate". Matching series IDs are fetched alongside any explicit Series IDs, up to Max Series.

## `observationStart` (type: `string`):

Earliest observation date to include (YYYY-MM-DD). Leave empty to include the full available history back to the series start.

## `observationEnd` (type: `string`):

Latest observation date to include (YYYY-MM-DD). Leave empty for the most recent available data.

## `recentObservations` (type: `integer`):

How many of the latest observation points (date + value) to include in each series record. Default 12.

## `includeFullHistory` (type: `boolean`):

Attach the complete historical observation array (every point in the range, not just the recent window) to each record. Opt-in add-on, billed per series only when a non-empty history is returned. Available to paid Apify plans.

## `includeAiSummary` (type: `boolean`):

Add an AI-written plain-English read of each series (trend, notable recent change, direction). Opt-in add-on, billed per series only when a usable summary is produced. Available to paid Apify plans.

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

Maximum number of series to return in one run (across Series IDs and Search Query). Free Apify plans are capped at 10.

## Actor input object example

```json
{
  "seriesIds": [
    "UNRATE",
    "CPIAUCSL",
    "FEDFUNDS"
  ],
  "searchQuery": "10 year treasury yield",
  "observationStart": "2015-01-01",
  "observationEnd": "2024-12-31",
  "recentObservations": 12,
  "includeFullHistory": false,
  "includeAiSummary": false,
  "maxResults": 10
}
```

# 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 = {
    "seriesIds": [
        "UNRATE",
        "CPIAUCSL",
        "FEDFUNDS"
    ],
    "recentObservations": 12,
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapers_lat/fred-economic-data-scraper").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": [
        "UNRATE",
        "CPIAUCSL",
        "FEDFUNDS",
    ],
    "recentObservations": 12,
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("scrapers_lat/fred-economic-data-scraper").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": [
    "UNRATE",
    "CPIAUCSL",
    "FEDFUNDS"
  ],
  "recentObservations": 12,
  "maxResults": 10
}' |
apify call scrapers_lat/fred-economic-data-scraper --silent --output-dataset

```

## MCP server setup

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

```

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/VkZLpQvju5Hw6b4pD/builds/UIYtuEFDQgjFf0EYa/openapi.json