GnistAI GnistAI
Log in

Getting Started with FRED (Federal Reserve)

U.S. economic time series — GDP, inflation, interest rates, and 800k+ indicators.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Economics

Data source: Federal Reserve Economic Data

Overview

FRED (Federal Reserve) wraps Federal Reserve Economic Data, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config 
{
  "mcpServers": {
    "gnist-fred": {
      "url": "https://context.gnist.ai/mcp/fred/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

get_series

Get economic time series observations from FRED. FRED (Federal Reserve Bank of St. Louis) hosts 800,000+ economic time series from 100+ sources: BLS, BEA, Census, Federal Reserve, IMF, OECD, World Bank, and more. This is the primary tool for fetching data when you already know the series ID. Common series IDs: - FEDFUNDS — Federal Funds Rate (monthly, %) - CPIAUCSL — CPI All Urban Consumers (monthly, index) - UNRATE — Civilian Unemployment Rate (monthly, %) - GDP — Gross Domestic Product (quarterly, billions USD) - DGS10 — 10-Year Treasury Yield (daily, %) - DGS2 — 2-Year Treasury Yield (daily, %) - T10Y2Y — 10-Year minus 2-Year Treasury spread (daily, %) - M2SL — M2 Money Stock (monthly, billions USD) - MORTGAGE30US — 30-Year Fixed Mortgage Rate (weekly, %) - DEXUSEU — USD/EUR exchange rate (daily) - PAYEMS — Total Nonfarm Payrolls (monthly, thousands) Args: series_id: FRED series identifier (e.g. "FEDFUNDS", "UNRATE", "GDP"). observation_start: Start date (YYYY-MM-DD). If omitted, fetches from the series start. observation_end: End date (YYYY-MM-DD). If omitted, fetches to the latest available observation. frequency: Aggregate to lower frequency. Options: "d" (daily), "w" (weekly), "bw" (biweekly), "m" (monthly), "q" (quarterly), "sa" (semiannual), "a" (annual). aggregation_method: How to aggregate when changing frequency. Options: "avg" (default), "sum", "eop". limit: Maximum observations to return (default 100, max 100000). Returns: series_id, title, units, frequency, seasonal_adjustment, last_updated, observation_count, and observations list of {"date": "YYYY-MM-DD", "value": float}.

ParameterTypeRequiredDescription
series_idstringrequiredFRED series identifier (e.g. "FEDFUNDS", "UNRATE", "GDP").
observation_startanyoptionalStart date (YYYY-MM-DD). If omitted, fetches from the series start.
observation_endanyoptionalEnd date (YYYY-MM-DD). If omitted, fetches to the latest available observation.
frequencyanyoptionalAggregate to lower frequency. Options: "d" (daily), "w" (weekly), "bw" (biweekly), "m" (monthly), "q" (quarterly), "sa" (semiannual), "a" (annual).
aggregation_methodanyoptionalHow to aggregate when changing frequency. Options: "avg" (default), "sum", "eop".
limitintegeroptionalMaximum observations to return (default 100, max 100000). (default: 100)
curl -X POST "https://context.gnist.ai/mcp/fred/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_series", "arguments": {"series_id": "FEDFUNDS"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/fred/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_id': 'FEDFUNDS'}, 'name': 'get_series'}},
)
print(resp.json())

search_series

Search FRED for economic time series matching a query. Searches across series titles, notes, and tags. Returns ranked results sorted by relevance. Use this when you don't know the series ID — then use get_series() or get_series_info() with the returned series_id. Example queries: - "federal funds rate" - "consumer price index urban" - "unemployment rate" - "GDP quarterly" - "Norway GDP" (FRED includes international series from IMF/OECD/World Bank) - "yield curve spread" - "housing starts" Args: query: Search terms to match against FRED series names and notes. limit: Maximum results to return (default 20, max 1000). Returns: count and list of matching series with series_id, title, frequency, units, seasonal_adjustment, date range, last_updated, popularity, and a truncated notes field.

ParameterTypeRequiredDescription
querystringrequiredSearch terms to match against FRED series names and notes.
limitintegeroptionalMaximum results to return (default 20, max 1000). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/fred/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_series", "arguments": {"query": "renewable energy"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/fred/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_series'}},
)
print(resp.json())

get_series_info

Get metadata for a FRED series without fetching observations. Useful for verifying a series ID and understanding its characteristics before fetching data: units, frequency, date range, and whether it is seasonally adjusted. Args: series_id: FRED series identifier (e.g. "FEDFUNDS", "UNRATE", "GDP"). Returns: Full metadata: series_id, title, frequency, units, seasonal_adjustment, observation_start, observation_end, last_updated, popularity, and notes.

ParameterTypeRequiredDescription
series_idstringrequiredFRED series identifier (e.g. "FEDFUNDS", "UNRATE", "GDP").
curl -X POST "https://context.gnist.ai/mcp/fred/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_series_info", "arguments": {"series_id": "FEDFUNDS"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/fred/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_id': 'FEDFUNDS'}, 'name': 'get_series_info'}},
)
print(resp.json())

get_category

Browse FRED's category hierarchy. FRED organizes its 800,000+ series into a tree of categories covering domains like Money, Banking & Finance; National Accounts; Prices; Labor Market; International Data; and more. Use this tool to discover series by topic area. category_id=0 returns the top-level categories. Args: category_id: Integer category ID. Default 0 returns the root categories. Pass a child category ID to drill down. IDs for common top-level categories: - 32991: Money, Banking & Finance - 10: National Accounts - 9: Population, Employment, & Labor Markets - 22: Prices - 3008: U.S. Regional Data - 32263: Business Cycles Returns: Category name, parent_id, children_count, and list of children each with id, name, parent_id.

ParameterTypeRequiredDescription
category_idintegeroptionalInteger category ID. Default 0 returns the root categories. Pass a child category ID to drill down. IDs for common top-level categories: - 32991: Money, Banking & Finance - 10: National Accounts - ... (default: 0)
curl -X POST "https://context.gnist.ai/mcp/fred/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_category", "arguments": {"category_id": 0}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/fred/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'category_id': 0}, 'name': 'get_category'}},
)
print(resp.json())

compare_series

Fetch multiple FRED series aligned to a common time axis. Retrieves all requested series and returns their observations aligned by date — only dates where all series have a value are included. Ideal for correlation analysis, charting, and comparing economic indicators. Example use cases: - compare_series(["FEDFUNDS", "DGS10", "DGS2"]) — Fed Funds vs. yield curve - compare_series(["UNRATE", "CPIAUCSL"], frequency="q") — unemployment vs. CPI quarterly - compare_series(["GDP", "PAYEMS"], observation_start="2020-01-01") — GDP vs. payrolls post-COVID Args: series_ids: List of 2–10 FRED series IDs to compare. observation_start: Start date (YYYY-MM-DD) applied to all series. observation_end: End date (YYYY-MM-DD) applied to all series. frequency: Aggregate all series to this frequency before aligning (e.g. "q" for quarterly, "a" for annual). Returns: series metadata dict (title, units, frequency per series), aligned_observation_count, and observations list where each row is {"date": "YYYY-MM-DD", "<series_id>": float, ...}.

ParameterTypeRequiredDescription
series_idslist[string]requiredList of 2–10 FRED series IDs to compare.
observation_startanyoptionalStart date (YYYY-MM-DD) applied to all series.
observation_endanyoptionalEnd date (YYYY-MM-DD) applied to all series.
frequencyanyoptionalAggregate all series to this frequency before aligning (e.g. "q" for quarterly, "a" for annual).
curl -X POST "https://context.gnist.ai/mcp/fred/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "compare_series", "arguments": {"series_ids": ["example"]}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/fred/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_ids': ['example']}, 'name': 'compare_series'}},
)
print(resp.json())

report_feedback

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/fred/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/fred/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_series to find items, then get_series to get full details. This two-step pattern is common for exploring data before drilling down.
Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does FRED (Federal Reserve) provide?

U.S. economic time series — GDP, inflation, interest rates, and 800k+ indicators. It exposes 6 tools: get_series, search_series, get_series_info, get_category, compare_series, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the FRED (Federal Reserve) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 6 tools.

Related Tutorials

Economic Indicators
Tutorial
BLS (Bureau of Labor Statistics)
Tutorial
DST (Statistics Denmark)
Tutorial
ESCO (Skills & Occupations)
Tutorial
Eurostat
Tutorial
Commodity Prices
Tutorial