fred_get_series

Retrieve any FRED time series data by ID with support for data transformations, frequency changes, and custom date ranges.

Overview

The fred_get_series tool is your primary interface for accessing actual economic data. It supports:

Retrieving observations for any of the 800,000+ series
Applying mathematical transformations (growth rates, percent changes)
Converting between frequencies (daily to monthly, monthly to quarterly)
Custom date ranges and vintage data
Multiple aggregation methods

Parameters

series_id

string

required

The FRED series ID to retrieve data for.Popular IDs:

GDP: Gross Domestic Product
UNRATE: Unemployment Rate
CPIAUCSL: Consumer Price Index
DFF: Federal Funds Rate
SP500: S&P 500 Index

Finding IDs: Use fred_search or fred_browse to discover series IDs

observation_start

string

Start date for observations in YYYY-MM-DD format.Examples:

2024-01-01: Start of 2024
2020-03-01: Beginning of pandemic period
2008-09-01: Start of financial crisis

Default: Series start date

observation_end

string

End date for observations in YYYY-MM-DD format.Examples:

2024-12-31: End of 2024
2023-12-31: Full year 2023

Default: Most recent available data

limit

number

default:"100000"

Maximum number of observations to return (1-100000).Usage:

Small limits for recent data: 12 for last year of monthly data
Large limits for historical analysis

offset

number

default:"0"

Number of observations to skip from the beginning.

sort_order

string

default:"asc"

Sort order of observations by date.Options:

asc: Chronological order (oldest first)
desc: Reverse chronological (newest first)

units

string

default:"lin"

Data transformation to apply.Options:

lin: Levels (no transformation) - raw values
chg: Change from previous period
ch1: Change from year ago
pch: Percent change from previous period
pc1: Percent change from year ago
pca: Compounded annual rate of change
cch: Continuously compounded rate of change
cca: Continuously compounded annual rate
log: Natural logarithm

Common uses:

pc1 for year-over-year inflation
pch for month-over-month growth
log for regression analysis

frequency

string

Frequency aggregation/conversion.Main options:

d: Daily
w: Weekly
bw: Biweekly
m: Monthly
q: Quarterly
sa: Semiannual
a: Annual

Weekly variants:

wef: Week Ending Friday
weth: Week Ending Thursday
wew: Week Ending Wednesday
wetu: Week Ending Tuesday
wem: Week Ending Monday
wesu: Week Ending Sunday
wesa: Week Ending Saturday

Default: Native series frequency

aggregation_method

string

default:"avg"

Method for aggregating to lower frequencies.Options:

avg: Average over period
sum: Sum of values in period
eop: End of period value

Usage examples:

avg for interest rates, prices
sum for flows like GDP, sales
eop for stock prices, levels

output_type

number

default:"1"

Output format type.Options:

1: Time series observations
2: Observations by vintage date
3: Observations by release date
4: Initial release only

Note: Types 2-4 for vintage analysis

vintage_dates

string

Specific vintage date(s) in YYYY-MM-DD format.Usage:

Single date: 2024-01-01
Date range: 2024-01-01:2024-12-31

Purpose: Retrieve data as it existed on specific dates

Examples

Basic Series Retrieval

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "UNRATE",
    "limit": 12
  }
}

Year-over-Year Inflation

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CPIAUCSL",
    "units": "pc1",
    "observation_start": "2024-01-01",
    "limit": 12
  }
}

Quarterly GDP Growth

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "GDPC1",
    "units": "pca",
    "observation_start": "2023-01-01",
    "observation_end": "2024-12-31"
  }
}

Convert Daily to Monthly

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DFF",
    "frequency": "m",
    "aggregation_method": "avg",
    "observation_start": "2024-01-01",
    "limit": 12
  }
}

Common Use Cases

Economic Dashboard

// GDP Growth (Quarterly)
{
  "series_id": "GDPC1",
  "units": "pca",
  "limit": 8
}

// Unemployment Rate (Monthly)
{
  "series_id": "UNRATE",
  "limit": 24
}

// Inflation Rate (Monthly YoY)
{
  "series_id": "CPIAUCSL",
  "units": "pc1",
  "limit": 24
}

// Federal Funds Rate (Daily)
{
  "series_id": "DFF",
  "limit": 30
}

Historical Analysis

// Long-term GDP growth
{
  "series_id": "GDPC1",
  "units": "pc1",
  "observation_start": "1950-01-01",
  "frequency": "a"
}

// Unemployment during recessions
{
  "series_id": "UNRATE",
  "observation_start": "2007-01-01",
  "observation_end": "2010-12-31"
}

// Inflation in the 1970s
{
  "series_id": "CPIAUCSL",
  "units": "pc1",
  "observation_start": "1970-01-01",
  "observation_end": "1979-12-31"
}

Financial Market Indicators

// 10-Year Treasury Yield
{
  "series_id": "DGS10",
  "limit": 252  // ~1 year of trading days
}

// Yield Curve (10Y-2Y Spread)
// Requires two calls and calculation
{
  "series_id": "T10Y2Y",
  "limit": 252
}

// S&P 500 Monthly Returns
{
  "series_id": "SP500",
  "units": "pch",
  "frequency": "m",
  "aggregation_method": "eop"
}

Transformation Examples

Growth Rate Calculations

Month-over-Month
Quarter-over-Quarter
Year-over-Year
Annualized Rate

{
  "series_id": "PAYEMS",
  "units": "chg",
  "limit": 12
}

Returns absolute change from previous month

{
  "series_id": "GDPC1",
  "units": "pch",
  "limit": 8
}

Returns percent change from previous quarter

{
  "series_id": "CPIAUCSL",
  "units": "pc1",
  "limit": 24
}

Returns percent change from same period last year

{
  "series_id": "GDPC1",
  "units": "pca",
  "limit": 8
}

Returns compounded annual rate of change

Frequency Conversions

Daily to Monthly
Monthly to Quarterly
Monthly to Annual
Daily to Weekly

{
  "series_id": "DFF",
  "frequency": "m",
  "aggregation_method": "avg"
}

Average daily values into monthly

{
  "series_id": "CPIAUCSL",
  "frequency": "q",
  "aggregation_method": "avg"
}

Average monthly values into quarterly

{
  "series_id": "UNRATE",
  "frequency": "a",
  "aggregation_method": "avg"
}

Average monthly values into annual

{
  "series_id": "DEXUSEU",
  "frequency": "wef",
  "aggregation_method": "eop"
}

Week-ending Friday values

Popular Series Reference

Key Economic Indicators

Series ID	Description	Frequency	Common Transform
GDP	Nominal GDP	Quarterly	`units: "pch"`
GDPC1	Real GDP	Quarterly	`units: "pca"`
UNRATE	Unemployment Rate	Monthly	None (already %)
PAYEMS	Nonfarm Payrolls	Monthly	`units: "chg"`
CPIAUCSL	CPI All Urban	Monthly	`units: "pc1"`
CPILFESL	Core CPI	Monthly	`units: "pc1"`
PCEPI	PCE Price Index	Monthly	`units: "pc1"`

Interest Rates

Series ID	Description	Frequency	Notes
DFF	Fed Funds Effective	Daily	Current policy rate
DGS10	10-Year Treasury	Daily	Long-term rate
DGS2	2-Year Treasury	Daily	Short-term rate
TB3MS	3-Month T-Bill	Monthly	Risk-free rate
MORTGAGE30US	30-Year Mortgage	Weekly	Consumer rate

Market Indicators

Series ID	Description	Frequency	Transform for Returns
SP500	S&P 500 Index	Daily	`units: "pch"`
DJIA	Dow Jones	Daily	`units: "pch"`
NASDAQCOM	NASDAQ Composite	Daily	`units: "pch"`
VIXCLS	VIX Volatility	Daily	None
DEXUSEU	EUR/USD Exchange	Daily	`units: "pch"`

Error Handling

Common Errors

Error	Cause	Solution
`Invalid series ID`	Series doesn’t exist	Use fred_search to find correct ID
`No data in range`	Date range has no data	Check series start/end dates
`Invalid transformation`	Transform not applicable	Some transforms need positive values
`Frequency conversion error`	Can’t convert to requested frequency	Check if conversion makes sense

Validation Rules

Important constraints:

Dates must be in YYYY-MM-DD format
observation_start must be ≤ observation_end
Some transformations require positive values
Not all frequency conversions are valid

Best Practices

Know Your Data

Check series metadata (frequency, units, seasonal adjustment) before retrieval

Use Appropriate Transforms

Match transformation to analysis needs (growth rates for trends, logs for regression)

Consider Frequency

Align data frequencies when comparing multiple series

Handle Missing Data

Some series have gaps; check for null values in observations

Plan Queries Carefully

Think through data needs to minimize redundant requests

fred_search

Find series IDs to retrieve

fred_browse

Explore available categories

API Tools

​fred_get_series

​Overview

​Parameters

​Examples

​Basic Series Retrieval

​Year-over-Year Inflation

​Quarterly GDP Growth

​Convert Daily to Monthly

​Common Use Cases

​Economic Dashboard

​Historical Analysis

​Financial Market Indicators

​Transformation Examples

​Growth Rate Calculations

​Frequency Conversions

​Popular Series Reference

​Key Economic Indicators

​Interest Rates

​Market Indicators

​Error Handling

​Common Errors

​Validation Rules

​Best Practices

​Related Tools

fred_search

fred_browse

fred_get_series

Overview

Parameters

Examples

Basic Series Retrieval

Year-over-Year Inflation

Quarterly GDP Growth

Convert Daily to Monthly

Common Use Cases

Economic Dashboard

Historical Analysis

Financial Market Indicators

Transformation Examples

Growth Rate Calculations

Frequency Conversions

Popular Series Reference

Key Economic Indicators

Interest Rates

Market Indicators

Error Handling

Common Errors

Validation Rules

Best Practices

Related Tools