manus-skills/.kortix/opencode/skills/data/database-lookup/references/fred.md

FRED (Federal Reserve Economic Data) API Reference

Overview

The FRED API, provided by the Federal Reserve Bank of St. Louis, offers access to over 800,000 economic time series from 100+ sources. Covers GDP, employment, inflation, interest rates, money supply, trade, housing, and much more.

Base URL

https://api.stlouisfed.org/fred

Authentication

• API Key: REQUIRED. Register at https://fred.stlouisfed.org/docs/api/api_key.html
• Pass as query parameter: &api_key=YOUR_KEY

Rate Limits

• 120 requests per minute per API key.
• No daily limit documented, but excessive use may trigger throttling.

Common Parameters (apply to most endpoints)

Parameter	Type	Required	Default	Description
api_key	string	Yes	-	Your FRED API key.
file_type	string	No	xml	Response format: xml or json.
realtime_start	string	No	today	Start of real-time period YYYY-MM-DD.
realtime_end	string	No	today	End of real-time period YYYY-MM-DD.

---

Key Endpoints

1. Series Observations (Time Series Data)

GET /fred/series/observations

Returns the data values for an economic time series.

Parameters:

Parameter	Type	Required	Default	Description
series_id	string	Yes	-	FRED series ID (e.g., GDP, UNRATE, CPIAUCSL).
observation_start	string	No	1776-07-04	Start date YYYY-MM-DD.
observation_end	string	No	9999-12-31	End date YYYY-MM-DD.
units	string	No	lin	Data transformation: lin (levels), chg (change), ch1 (change from year ago), pch (% change), pc1 (% change from year ago), pca (compounded annual % change), cch (continuously compounded rate of change), cca (continuously compounded annual rate), log (natural log).
frequency	string	No	(native)	Aggregation frequency: d, w, bw, m, q, sa, a (daily through annual).
aggregation_method	string	No	avg	avg, sum, eop (end of period).
sort_order	string	No	asc	asc or desc.
limit	int	No	100000	Max observations returned (max 100000).
offset	int	No	0	Pagination offset.

Example:

https://api.stlouisfed.org/fred/series/observations?series_id=GDP&api_key=YOUR_KEY&file_type=json&observation_start=2020-01-01&observation_end=2024-12-31&units=pch&frequency=q

Response:

{
  "realtime_start": "2024-11-01",
  "realtime_end": "2024-11-01",
  "observation_start": "2020-01-01",
  "observation_end": "2024-12-31",
  "units": "Percent Change",
  "output_type": 1,
  "file_type": "json",
  "order_by": "observation_date",
  "sort_order": "asc",
  "count": 20,
  "offset": 0,
  "limit": 100000,
  "observations": [
    {
      "realtime_start": "2024-11-01",
      "realtime_end": "2024-11-01",
      "date": "2020-01-01",
      "value": "-1.3"
    },
    {
      "realtime_start": "2024-11-01",
      "realtime_end": "2024-11-01",
      "date": "2020-04-01",
      "value": "-8.4"
    }
  ]
}

Note: value is always a string. Missing values appear as ".".

---

2. Series Info (Metadata)

GET /fred/series

Returns metadata for a series.

Parameters:

Parameter	Type	Required	Description
series_id	string	Yes	FRED series ID.

Example:

https://api.stlouisfed.org/fred/series?series_id=UNRATE&api_key=YOUR_KEY&file_type=json

Response:

{
  "realtime_start": "2024-11-01",
  "realtime_end": "2024-11-01",
  "seriess": [
    {
      "id": "UNRATE",
      "title": "Unemployment Rate",
      "observation_start": "1948-01-01",
      "observation_end": "2024-10-01",
      "frequency": "Monthly",
      "frequency_short": "M",
      "units": "Percent",
      "units_short": "%",
      "seasonal_adjustment": "Seasonally Adjusted",
      "seasonal_adjustment_short": "SA",
      "last_updated": "2024-11-01 07:41:02-05",
      "popularity": 95,
      "notes": "The unemployment rate represents..."
    }
  ]
}

---

3. Series Search

GET /fred/series/search

Search for series by keywords.

Parameters:

Parameter	Type	Required	Default	Description
search_text	string	Yes	-	Keywords to search.
search_type	string	No	full_text	full_text or series_id.
order_by	string	No	search_rank	search_rank, series_id, title, units, frequency, seasonal_adjustment, realtime_start, realtime_end, last_updated, observation_start, observation_end, popularity, group_popularity.
sort_order	string	No	asc	asc or desc.
limit	int	No	1000	Max results (max 1000).
offset	int	No	0	Pagination offset.
filter_variable	string	No	-	frequency, units, seasonal_adjustment.
filter_value	string	No	-	Value to filter on (e.g., Monthly).
tag_names	string	No	-	Semicolon-delimited tags to filter (e.g., gdp;quarterly).

Example:

https://api.stlouisfed.org/fred/series/search?search_text=consumer+price+index&api_key=YOUR_KEY&file_type=json&limit=5

Response:

{
  "realtime_start": "2024-11-01",
  "realtime_end": "2024-11-01",
  "order_by": "search_rank",
  "sort_order": "asc",
  "count": 1256,
  "offset": 0,
  "limit": 5,
  "seriess": [
    {
      "id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "observation_start": "1947-01-01",
      "observation_end": "2024-09-01",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100",
      "seasonal_adjustment": "Seasonally Adjusted",
      "popularity": 95
    }
  ]
}

---

4. Category Lookup

GET /fred/category

Get info for a specific category.

Parameters:

Parameter	Type	Required	Description
category_id	int	Yes	Category ID (0 = root).

Example:

https://api.stlouisfed.org/fred/category?category_id=0&api_key=YOUR_KEY&file_type=json

GET /fred/category/children

Get child categories.

Example:

https://api.stlouisfed.org/fred/category/children?category_id=0&api_key=YOUR_KEY&file_type=json

GET /fred/category/series

Get all series in a category.

Parameters:

Parameter	Type	Required	Description
category_id	int	Yes	Category ID.
limit	int	No	Max results (max 1000).
offset	int	No	Pagination offset.

Example:

https://api.stlouisfed.org/fred/category/series?category_id=125&api_key=YOUR_KEY&file_type=json

---

5. Releases

GET /fred/releases

Get all economic data releases.

Example:

https://api.stlouisfed.org/fred/releases?api_key=YOUR_KEY&file_type=json

GET /fred/release/series

Get all series in a specific release.

Parameters:

Parameter	Type	Required	Description
release_id	int	Yes	Release ID.

Example:

https://api.stlouisfed.org/fred/release/series?release_id=53&api_key=YOUR_KEY&file_type=json

---

6. Tags

GET /fred/tags

Get all tags and their frequency of use.

GET /fred/series/search/tags

Get tags matching a series search.

Example:

https://api.stlouisfed.org/fred/series/search/tags?series_search_text=mortgage+rate&api_key=YOUR_KEY&file_type=json

---

Commonly Used Series IDs

Series ID	Description
GDP	Gross Domestic Product (quarterly, billions $)
GDPC1	Real GDP (chained 2017 dollars)
A191RL1Q225SBEA	Real GDP growth rate (annualized quarterly)
UNRATE	Unemployment Rate (monthly, %)
PAYEMS	Total Nonfarm Payrolls (monthly, thousands)
CPIAUCSL	CPI All Urban Consumers (monthly, index)
CPILFESL	Core CPI (excl. food & energy)
PCEPI	PCE Price Index
PCEPILFE	Core PCE Price Index
FEDFUNDS	Federal Funds Effective Rate (monthly, %)
DFF	Federal Funds Effective Rate (daily)
DGS10	10-Year Treasury Constant Maturity Rate (daily)
DGS2	2-Year Treasury Rate (daily)
T10Y2Y	10Y-2Y Treasury Spread
MORTGAGE30US	30-Year Fixed Mortgage Rate (weekly)
M2SL	M2 Money Stock (monthly)
HOUST	Housing Starts (monthly, thousands)
RSAFS	Retail Sales (monthly, millions $)
INDPRO	Industrial Production Index
UMCSENT	U. of Michigan Consumer Sentiment
SP500	S&P 500 Index (daily)
VIXCLS	CBOE Volatility Index (daily)
DEXUSEU	USD/EUR Exchange Rate (daily)
DCOILWTICO	WTI Crude Oil Price (daily)
BOPGSTB	Trade Balance (monthly, millions $)
GFDEBTN	Federal Debt Total Public Debt

Notes

• Real-time periods: FRED supports vintage data. The realtime_start/realtime_end parameters let you retrieve data as it was known at a specific point in time (useful for analyzing data revisions).
• The units parameter for transformations is very powerful -- it avoids having to compute percent changes client-side.
• Values are returned as strings; "." means missing/unavailable.
• For FRED bulk data, they offer a download API at https://api.stlouisfed.org/geofred/ for geographic/regional data.