Fred

Fred Get Series

fred_get_series

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max observations, newest first (1-100000, default 20)
`units`	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
`_apiKey`	Yes	FRED API key
`frequency`	No	Frequency aggregation (optional). Codes: d, w, bw, m, q, sa, a — English words also accepted (daily/weekly/biweekly/monthly/quarterly/semiannual/annual).
`series_id`	Yes	FRED series ID (e.g., "MORTGAGE30US", "HOUST", "CSUSHPISA")
`sort_order`	No	Observation order: desc = newest first (default), asc = oldest first.
`observation_end`	No	End date in YYYY-MM-DD format (optional)
`observation_start`	No	Start date in YYYY-MM-DD format (optional)

Output Schema

TableJSON Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 22, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "MORTGAGE30US"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_end": "2024-12-31",
-    "observation_start": "2020-01-01",
-    "series_id": "HOUST",
-    "units": "pch"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "DBAA"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_start": "2025-01-01",
-    "series_id": "RHORUSQ156N"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "UNRATE"
-  }
-]New value: +[
+  {
+    "series_id": "MORTGAGE30US"
+  },
+  {
+    "observation_end": "2024-12-31",
+    "observation_start": "2020-01-01",
+    "series_id": "HOUST",
+    "units": "pch"
+  },
+  {
+    "series_id": "DBAA"
+  },
+  {
+    "observation_start": "2025-01-01",
+    "series_id": "RHORUSQ156N"
+  },
+  {
+    "series_id": "UNRATE"
+  }
+]

Changed14 schema fields changedAug 31, 2026

addedInput schema / properties / sort_order

Added value: +{
+  "description": "Observation order: desc = newest first (default), asc = oldest first.",
+  "enum": [
+    "asc",
+    "desc"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / count / description

Previous value: -"Total number of observations returned"New value: +"Total observations FRED holds for the requested window — NOT the number returned; compare with `returned`."

addedOutput schema / properties / frequency

Added value: +{
+  "description": "Publication frequency of the series.",
+  "type": "string"
+}

addedOutput schema / properties / note

Added value: +{
+  "description": "Present when the list was truncated or an empty request window was widened.",
+  "type": "string"
+}

changedOutput schema / properties / observation_end / description

Previous value: -"End date of observations in YYYY-MM-DD format"New value: +"Last date this series actually covers, from FRED's series metadata."

addedOutput schema / properties / observation_order

Added value: +{
+  "description": "Order of the `observations` array. Defaults to newest_first; pass sort_order:'asc' for oldest_first.",
+  "enum": [
+    "newest_first",
+    "oldest_first"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / observation_start / description

Previous value: -"Start date of observations in YYYY-MM-DD format"New value: +"First date this series actually covers, from FRED's series metadata."

addedOutput schema / properties / requested_end

Added value: +{
+  "description": "The observation_end the caller passed, echoed back. Absent when the caller passed none.",
+  "type": "string"
+}

addedOutput schema / properties / requested_start

Added value: +{
+  "description": "The observation_start the caller passed, echoed back. Absent when the caller passed none.",
+  "type": "string"
+}

addedOutput schema / properties / returned

Added value: +{
+  "description": "How many observations are actually in `observations` (capped by `limit`, default 20).",
+  "type": "number"
+}

addedOutput schema / properties / series_title

Added value: +{
+  "description": "Series title from FRED metadata.",
+  "type": "string"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when `returned` is less than `count` — raise `limit` to see the rest.",
+  "type": "boolean"
+}

addedOutput schema / properties / units

Added value: +{
+  "description": "Units the values are reported in.",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "series_id",
-  "count",
-  "observation_start",
-  "observation_end",
-  "observations"
-]New value: +[
+  "series_id",
+  "count",
+  "observations"
+]

Changed1 schema field changedAug 6, 2026

addedInput schema / properties / limit

Added value: +{
+  "description": "Max observations, newest first (1-100000, default 20)",
+  "type": "number"
+}

Changed1 schema field changedAug 4, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "MORTGAGE30US"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_end": "2024-12-31",
-    "observation_start": "2020-01-01",
-    "series_id": "HOUST",
-    "units": "pch"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "DBAA"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_start": "2025-01-01",
-    "series_id": "RHORUSQ156N"
-  }
-]New value: +[
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "MORTGAGE30US"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_end": "2024-12-31",
+    "observation_start": "2020-01-01",
+    "series_id": "HOUST",
+    "units": "pch"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "DBAA"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_start": "2025-01-01",
+    "series_id": "RHORUSQ156N"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "UNRATE"
+  }
+]

Changed1 schema field changedJul 25, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "MORTGAGE30US"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_end": "2024-12-31",
-    "observation_start": "2020-01-01",
-    "series_id": "HOUST",
-    "units": "pch"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "DBAA"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "RHORUSQ156N"
-  }
-]New value: +[
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "MORTGAGE30US"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_end": "2024-12-31",
+    "observation_start": "2020-01-01",
+    "series_id": "HOUST",
+    "units": "pch"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "DBAA"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_start": "2025-01-01",
+    "series_id": "RHORUSQ156N"
+  }
+]

Changed1 schema field changedJul 24, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "MORTGAGE30US"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_end": "2024-12-31",
-    "observation_start": "2020-01-01",
-    "series_id": "HOUST",
-    "units": "pch"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "DBAA"
-  }
-]New value: +[
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "MORTGAGE30US"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_end": "2024-12-31",
+    "observation_start": "2020-01-01",
+    "series_id": "HOUST",
+    "units": "pch"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "DBAA"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "RHORUSQ156N"
+  }
+]

Changed1 schema field changedJul 21, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-fred-api-key",
-    "series_id": "MORTGAGE30US"
-  },
-  {
-    "_apiKey": "your-fred-api-key",
-    "observation_end": "2024-12-31",
-    "observation_start": "2020-01-01",
-    "series_id": "HOUST",
-    "units": "pch"
-  }
-]New value: +[
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "MORTGAGE30US"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_end": "2024-12-31",
+    "observation_start": "2020-01-01",
+    "series_id": "HOUST",
+    "units": "pch"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "DBAA"
+  }
+]

Changed1 schema field changedJun 27, 2026

changedInput schema / properties / frequency / description

Previous value: -"Frequency aggregation: d, w, bw, m, q, sa, a (optional)"New value: +"Frequency aggregation (optional). Codes: d, w, bw, m, q, sa, a — English words also accepted (daily/weekly/biweekly/monthly/quarterly/semiannual/annual)."

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Total number of observations returned",
+      "type": "number"
+    },
+    "observation_end": {
+      "description": "End date of observations in YYYY-MM-DD format",
+      "type": "string"
+    },
+    "observation_start": {
+      "description": "Start date of observations in YYYY-MM-DD format",
+      "type": "string"
+    },
+    "observations": {
+      "description": "Array of date-value pairs",
+      "items": {
+        "properties": {
+          "date": {
+            "description": "Observation date in YYYY-MM-DD format",
+            "type": "string"
+          },
+          "value": {
+            "description": "Numeric value or null if missing",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "date",
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "series_id": {
+      "description": "The requested FRED series ID",
+      "type": "string"
+    }
+  },
+  "required": [
+    "series_id",
+    "count",
+    "observation_start",
+    "observation_end",
+    "observations"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "_apiKey": "your-fred-api-key",
+    "series_id": "MORTGAGE30US"
+  },
+  {
+    "_apiKey": "your-fred-api-key",
+    "observation_end": "2024-12-31",
+    "observation_start": "2020-01-01",
+    "series_id": "HOUST",
+    "units": "pch"
+  }
+]

First observedApr 22, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already carry the safety profile (readOnlyHint, idempotentHint, openWorldHint, non-destructive), lowering the bar. The description adds meaningful behavioral context beyond that: the exact 400 failure mode for invalid IDs, the return contract (dates + values + units), the aggregate-only granularity constraint, and monthly/quarterly reporting frequency. It does not cover rate limits or auth-failure behavior, but the added context is substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (~230 words) but front-loaded with purpose and every sentence earns its place: examples carry semantic translations the schema examples lack, and the prominent DO NOT GUESS warning is critical failure prevention. It is dense rather than padded; only slight trimming of the example list would tighten it further.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich supported context (100% parameter schema coverage, full annotations, and an output schema), the description is complete: it covers purpose, scope, failure modes, alternatives, and the ID-discovery workflow. An agent can safely and correctly invoke this tool for US macro questions and be routed elsewhere for foreign data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by giving semantically annotated series_id examples (e.g., RHORUSQ156N disambiguated as homeownership rate 'distinct from the mortgage interest rate') and by warning against the ISO3+METRIC naming pattern that does not exist on FRED. For a tool whose critical parameter is an opaque ID string, this materially improves correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('historical time-series for US economic indicators from FRED') with concrete scope (macro, Fed, metro-level US data). It distinguishes itself from siblings by explicitly naming fred_search (for finding IDs) and worldbank_get_indicator (for non-US data), so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('Use for macro, Fed, and metro-level US indicator questions'), when-not-to-use ('DO NOT GUESS a non-US series ID'), and a named alternative with a concrete example indicator (worldbank_get_indicator, SL.UEM.TOTL.ZS). It also prescribes the prerequisite workflow: 'call fred_search first rather than inventing one.' Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Fred tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Fred Get Series

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources