# FRED Economic Data Scraper (`muhammadafzal/fred-economic-data-scraper`) Actor

Scrape official FRED economic series metadata and dated observations for analysts, researchers, dashboards, and AI data workflows without requiring a FRED API key.

- **URL**: https://apify.com/muhammadafzal/fred-economic-data-scraper.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Other, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.39 / 1,000 fred observations

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?

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 Scraper

> **Free-plan limit:** Apify free-plan users receive at most 5 delivered records per run. Paid users may use the Actor’s configured result limit.

Scrape official Federal Reserve Economic Data (FRED) series into analysis-ready observation rows without requiring users to supply a FRED API key.

The Actor reads public series metadata from `fred.stlouisfed.org/series/{ID}` and observations from FRED's own graph CSV export. It is designed for economists, analysts, researchers, dashboards, AI agents, and scheduled data pipelines that already know the FRED series IDs they need.

### What it extracts

Each dataset item represents one dated observation and repeats the series context needed to understand it independently.

| Field | Meaning |
|---|---|
| `seriesId` | Canonical FRED series ID, such as `GDP` or `UNRATE` |
| `title` | Human-readable series name |
| `observationDate` | Date attached to the observation |
| `value` | Numeric value, or `null` when a requested missing value is retained |
| `rawValue` | Original FRED CSV value text |
| `units` | Units shown by FRED |
| `seasonalAdjustment` | Seasonal-adjustment qualifier, when available |
| `frequency` | Daily, monthly, quarterly, annual, or another FRED frequency |
| `source` / `release` | Originating institution and named release |
| `notes` | FRED's explanatory series notes |
| `lastUpdated` | Update timestamp shown on the series page |
| `observationStart` / `observationEnd` | Full series coverage shown by FRED |
| `sourceUrl` / `csvUrl` | Official provenance URLs |
| `scrapedAt` | UTC collection timestamp |

### When to use it

Use this Actor when you know one or more FRED series IDs and want keyless, structured observations for spreadsheets, BI tools, research notebooks, monitoring jobs, or agent workflows. Common examples include `GDP`, `CPIAUCSL`, `UNRATE`, `FEDFUNDS`, and `DGS10`.

This Actor does not search FRED by keyword, retrieve ALFRED vintage revisions, or expose the full authenticated FRED API. Use FRED's documented API with your own key when you need category search, releases in bulk, vintage dates, transformations, or other API-only capabilities.

### Input

| Input | Default | Description |
|---|---:|---|
| `seriesIds` | `GDP`, `CPIAUCSL`, `UNRATE` | 1-50 exact FRED series IDs |
| `startDate` | `2020-01-01` | Earliest observation date, `YYYY-MM-DD` |
| `endDate` | latest | Optional last observation date |
| `maxResults` | `1000` | Total dataset-item cap across series |
| `maxObservationsPerSeries` | `1000` | Per-series cap |
| `sortOrder` | `ascending` | `ascending` or `descending` within each series |
| `includeMissingValues` | `false` | Keep FRED `.` gaps as `value: null` |

Example input:

```json
{
  "seriesIds": ["GDP", "CPIAUCSL", "UNRATE"],
  "startDate": "2024-01-01",
  "endDate": "2025-12-31",
  "maxResults": 500,
  "maxObservationsPerSeries": 250,
  "sortOrder": "descending",
  "includeMissingValues": false
}
```

Run it through the Apify API after setting `APIFY_TOKEN` in your shell:

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~fred-economic-data-scraper/runs" \
  -H "Authorization: Bearer ${APIFY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"seriesIds":["GDP","UNRATE"],"startDate":"2024-01-01","maxResults":100}'
```

### Output example

```json
{
  "seriesId": "GDP",
  "title": "Gross Domestic Product",
  "observationDate": "2025-10-01",
  "value": 31422.526,
  "rawValue": "31422.526",
  "units": "Billions of Dollars",
  "seasonalAdjustment": "Seasonally Adjusted Annual Rate",
  "frequency": "Quarterly",
  "source": "U.S. Bureau of Economic Analysis",
  "release": "Gross Domestic Product",
  "notes": "Gross domestic product (GDP) is the market value of goods and services produced in the United States.",
  "lastUpdated": "Aug 26, 2026 7:49 AM CDT",
  "observationStart": "1947-01-01",
  "observationEnd": "2026-04-01",
  "sourceUrl": "https://fred.stlouisfed.org/series/GDP",
  "csvUrl": "https://fred.stlouisfed.org/graph/fredgraph.csv?id=GDP&cosd=2024-01-01&coed=2025-12-31",
  "scrapedAt": "2026-08-28T10:00:00.000Z"
}
```

The `OUTPUT` and `SUMMARY` key-value-store records contain per-series outcomes, warnings, truncation flags, result counts, and expected PPE event counts. Invalid IDs never create fabricated observation rows.

### Pricing

This Actor uses **pay-per-event** pricing. These are the current Apify Store event prices:

| Event | Price (USD) | When it is charged |
|---|---:|---|
| `apify-default-dataset-item` | FREE: $0.00669; BRONZE: $0.00669; SILVER: $0.00669; GOLD: $0.00439; PLATINUM: $0.00439; DIAMOND: $0.00439 | FRED observation — One normalized, schema-valid FRED economic observation written to the default dataset. |
| `apify-actor-start` | $0.005 | Actor Start — Charged when the Actor starts running. Number of events charged depends on Actor memory (one event per GB, minimum one event). — Charged once per run. |

Apify platform usage for this Actor run is included alongside the event prices above; no separate per-run platform-usage fee is passed to users.

This covers Apify platform usage for this Actor run. Other Apify products or usage outside this Actor run may still follow your account plan.

### Reliability and limits

Requests use bounded timeouts, three attempts for transient failures, and direct official FRED pages only. Series are fetched concurrently but written in the same order as `seriesIds`; observations remain stable within each series. A missing series, access block, malformed response, or partial failure is recorded in `OUTPUT` instead of becoming a fake dataset record. Valid results from other series are preserved.

The Actor accepts at most 50 series, 10,000 total observations, and 5,000 observations per series. Defaults are deliberately small enough for automated testing and routine scheduled runs. FRED can revise economic data, so repeated runs may legitimately return different values or update timestamps.

### Legal and data use

FRED is a service of the Federal Reserve Bank of St. Louis. Review the source, release, copyright, citation, and usage notes attached to each series before redistributing data. This Actor is independent and is not endorsed by the Federal Reserve Bank of St. Louis. It accesses only public pages and exports, does not bypass authentication or access controls, and does not collect personal data.

For problems, include the run ID, non-secret input, affected series IDs, and the `OUTPUT` record in your Apify support message.

# Changelog

This Actor's version history is a separate document: https://apify.com/muhammadafzal/fred-economic-data-scraper/changelog.md

# Actor input Schema

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

Use this when you know the FRED series IDs to retrieve. Enter one ID per line, such as GDP, CPIAUCSL, or UNRATE. Defaults to three popular US indicators; this field does not accept search keywords or full URLs.

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

Use this to return observations on or after a date in YYYY-MM-DD format, such as 2020-01-01. Defaults to 2020-01-01; this is an observation date, not a FRED release or vintage date.

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

Use this to return observations on or before a date in YYYY-MM-DD format, such as 2025-12-31. Leave it unset for the latest available observation; this is not a real-time vintage cutoff.

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

Use this to cap dataset items across all requested series. Enter 1-10000; the default is 1000. This limit counts individual dated observations, not series.

## `maxObservationsPerSeries` (type: `integer`):

Use this to keep any one series from consuming the whole result budget. Enter 1-5000; the default is 1000. The selected sort order decides which observations are kept first.

## `sortOrder` (type: `string`):

Use ascending for oldest-to-newest data or descending for newest-to-oldest data. Defaults to ascending; series remain grouped in the same order as seriesIds.

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

Use this when gaps represented by a period in FRED CSV data must remain explicit. Defaults to false; when true, missing observations have value null and rawValue ".".

## Actor input object example

```json
{
  "seriesIds": [
    "GDP",
    "CPIAUCSL",
    "UNRATE"
  ],
  "startDate": "2020-01-01",
  "maxResults": 1000,
  "maxObservationsPerSeries": 1000,
  "sortOrder": "ascending",
  "includeMissingValues": false
}
```

# Actor output Schema

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

Schema-validated economic observation records in the default dataset.

## `summary` (type: `string`):

Per-series outcomes, warnings, limits, and expected PPE event counts.

# 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("muhammadafzal/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": [
        "GDP",
        "CPIAUCSL",
        "UNRATE",
    ],
    "startDate": "2020-01-01",
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/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": [
    "GDP",
    "CPIAUCSL",
    "UNRATE"
  ],
  "startDate": "2020-01-01"
}' |
apify call muhammadafzal/fred-economic-data-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/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/qMAcKSi9sULptIWsV/builds/IbZCSZIm079vLzliW/openapi.json