`fred_get_series`

Pack: fred · Endpoint: https://gateway.pipeworx.io/fred/mcp

AUTHORITATIVE historical time-series for US economic indicators from FRED (Federal Reserve Bank of St. Louis — the official US macroeconomic data repository, 800k+ series). Every series is an AGGREGATE for a whole country, state, or METROPOLITAN AREA (e.g. the Phoenix or Oklahoma City metro), reported monthly or quarterly. Pass a series ID like “MORTGAGE30US” (30y mortgage rate), “UNRATE” (unemployment), “CPIAUCSL” (CPI), “GDP”, “FEDFUNDS” (Fed funds rate), “HOUST” (housing starts), “RHORUSQ156N” (US homeownership rate — the percent of households that OWN their home, distinct from the mortgage interest rate). Returns dates + values + the indicator’s units. Use for macro, Fed, and metro-level US indicator questions. DO NOT GUESS a non-US series ID by pattern-matching a US one — “DEUUNRATE”, “JPNUNRATE”, “CANUNRATE” and similar codes do NOT exist on FRED and 400 with “the series does not exist”. For a NON-US country’s unemployment/GDP/inflation/population, use worldbank_get_indicator (ISO country code + indicator, e.g. SL.UEM.TOTL.ZS for unemployment) instead — it is the reliable source for foreign macro data. If you don’t know a FRED series ID, call fred_search first rather than inventing one.

Parameters

Name	Type	Required	Description
`series_id`	string	yes	FRED series ID (e.g., “MORTGAGE30US”, “HOUST”, “CSUSHPISA”)
`observation_start`	string	no	Start date in YYYY-MM-DD format (optional)
`observation_end`	string	no	End date in YYYY-MM-DD format (optional)
`frequency`	string	no	Frequency aggregation (optional). Codes: d, w, bw, m, q, sa, a — English words also accepted (daily/weekly/biweekly/monthly/quarterly/semiannual/annual).
`units`	string	no	Data transformation: lin (levels), chg (change), ch1 (change from year ago), pch (% change), pc1 (% change from year ago), pca (compounded annual rate of change), cch (continuously compounded rate of change), cca (continuously compounded annual rate of change), log (natural log). Default: lin
`limit`	number	no	Max observations, newest first (1-100000, default 20)
`sort_order`	string	no	Observation order: desc = newest first (default), asc = oldest first.
`_apiKey`	string	yes	FRED API key

Example call

Arguments

{
  "series_id": "MORTGAGE30US",
  "_apiKey": "your-fred-api-key"
}

curl

curl -X POST https://gateway.pipeworx.io/fred/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"fred_get_series","arguments":{"series_id":"MORTGAGE30US","_apiKey":"your-fred-api-key"}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('fred_get_series', {
  "series_id": "MORTGAGE30US",
  "_apiKey": "your-fred-api-key"
});

More examples

{
  "series_id": "HOUST",
  "observation_start": "2020-01-01",
  "observation_end": "2024-12-31",
  "units": "pch",
  "_apiKey": "your-fred-api-key"
}

{
  "series_id": "DBAA",
  "_apiKey": "your-fred-api-key"
}

{
  "series_id": "RHORUSQ156N",
  "observation_start": "2025-01-01",
  "_apiKey": "your-fred-api-key"
}

{
  "series_id": "UNRATE",
  "_apiKey": "your-fred-api-key"
}

Response shape

Always returns: series_id, count, observations

Field	Type	Description
`series_id`	string	The requested FRED series ID
`count`	number	Total observations FRED holds for the requested window — NOT the number returned; compare with `returned`.
`returned`	number	How many observations are actually in `observations` (capped by `limit`, default 20).
`truncated`	boolean	True when `returned` is less than `count` — raise `limit` to see the rest.
`observation_order`	string	Order of the `observations` array. Defaults to newest_first; pass sort_order:‘asc’ for oldest_first.
`observation_start`	string	First date this series actually covers, from FRED’s series metadata.
`observation_end`	string	Last date this series actually covers, from FRED’s series metadata.
`requested_start`	string	The observation_start the caller passed, echoed back. Absent when the caller passed none.
`requested_end`	string	The observation_end the caller passed, echoed back. Absent when the caller passed none.
`observations`	array	Array of date-value pairs
`note`	string	Present when the list was truncated or an empty request window was widened.
`series_title`	string	Series title from FRED metadata.
`units`	string	Units the values are reported in.
`frequency`	string	Publication frequency of the series.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "series_id": {
      "type": "string",
      "description": "The requested FRED series ID"
    },
    "count": {
      "type": "number",
      "description": "Total observations FRED holds for the requested window — NOT the number returned; compare with `returned`."
    },
    "returned": {
      "type": "number",
      "description": "How many observations are actually in `observations` (capped by `limit`, default 20)."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when `returned` is less than `count` — raise `limit` to see the rest."
    },
    "observation_order": {
      "type": "string",
      "enum": [
        "newest_first",
        "oldest_first"
      ],
      "description": "Order of the `observations` array. Defaults to newest_first; pass sort_order:'asc' for oldest_first."
    },
    "observation_start": {
      "type": "string",
      "description": "First date this series actually covers, from FRED's series metadata."
    },
    "observation_end": {
      "type": "string",
      "description": "Last date this series actually covers, from FRED's series metadata."
    },
    "requested_start": {
      "type": "string",
      "description": "The observation_start the caller passed, echoed back. Absent when the caller passed none."
    },
    "requested_end": {
      "type": "string",
      "description": "The observation_end the caller passed, echoed back. Absent when the caller passed none."
    },
    "observations": {
      "type": "array",
      "description": "Array of date-value pairs",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Observation date in YYYY-MM-DD format"
          },
          "value": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numeric value or null if missing"
          }
        },
        "required": [
          "date",
          "value"
        ]
      }
    },
    "note": {
      "type": "string",
      "description": "Present when the list was truncated or an empty request window was widened."
    },
    "series_title": {
      "type": "string",
      "description": "Series title from FRED metadata."
    },
    "units": {
      "type": "string",
      "description": "Units the values are reported in."
    },
    "frequency": {
      "type": "string",
      "description": "Publication frequency of the series."
    }
  },
  "required": [
    "series_id",
    "count",
    "observations"
  ]
}

Connect

Add this to your MCP client config, or use one-click install buttons:

{
  "mcpServers": {
    "fred": {
      "url": "https://gateway.pipeworx.io/fred/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

fred_get_series