Skip to main content
Glama
Sign In

Fred

by io.github.pipeworx-io
OverviewDiscussionsAdmin

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

NameRequiredDescriptionDefault
as_ofNoALFRED vintage query: return the data as it was PUBLISHED on this date (YYYY-MM-DD), before any later revisions. Shorthand for realtime_start=realtime_end=as_of. Omit for the default: today's latest-revised values (unchanged from before this parameter existed).
limitNoMax observations, newest first (1-100000, default 20)
unitsNoData 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
_apiKeyYesFRED API key
frequencyNoFrequency aggregation (optional). Codes: d, w, bw, m, q, sa, a — English words also accepted (daily/weekly/biweekly/monthly/quarterly/semiannual/annual).
series_idYesFRED series ID (e.g., "MORTGAGE30US", "HOUST", "CSUSHPISA")
sort_orderNoObservation order: desc = newest first (default), asc = oldest first.
realtime_endNoALFRED vintage query: end of the realtime (publication) window, YYYY-MM-DD. See realtime_start.
realtime_startNoALFRED vintage query: start of the realtime (publication) window, YYYY-MM-DD. Use with realtime_end for a custom vintage range; use `as_of` for the common single-date case. Omit for the default latest-revised behavior.
observation_endNoEnd date in YYYY-MM-DD format (optional)
observation_startNoStart date in YYYY-MM-DD format (optional)

Output Schema

NameRequiredDescriptionDefault
noteNoPresent when the list was truncated or an empty request window was widened.
countYesTotal observations FRED holds for the requested window — NOT the number returned; compare with `returned`.
unitsNoUnits the values are reported in.
vintageNoPresent only when the caller passed as_of/realtime_start/realtime_end. The resolved vintage query.
returnedNoHow many observations are actually in `observations` (capped by `limit`, default 20).
frequencyNoPublication frequency of the series.
series_idYesThe requested FRED series ID
truncatedNoTrue when `returned` is less than `count` — raise `limit` to see the rest.
observationsYesArray of date-value pairs
series_titleNoSeries title from FRED metadata.
requested_endNoThe observation_end the caller passed, echoed back. Absent when the caller passed none.
observation_endNoLast date this series actually covers, from FRED's series metadata.
requested_startNoThe observation_start the caller passed, echoed back. Absent when the caller passed none.
observation_orderNoOrder of the `observations` array. Defaults to newest_first; pass sort_order:'asc' for oldest_first.
observation_startNoFirst date this series actually covers, from FRED's series metadata.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / examples
      Previous 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"
-  }
-]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"
+  },
+  {
+    "series_id": "DEXUSEU"
+  },
+  {
+    "as_of": "2024-01-15",
+    "limit": 1,
+    "series_id": "GDPC1"
+  }
+]
    • addedInput schema / properties / as_of
      Added value: +{
+  "description": "ALFRED vintage query: return the data as it was PUBLISHED on this date (YYYY-MM-DD), before any later revisions. Shorthand for realtime_start=realtime_end=as_of. Omit for the default: today's latest-revised values (unchanged from before this parameter existed).",
+  "type": "string"
+}
    • addedInput schema / properties / realtime_end
      Added value: +{
+  "description": "ALFRED vintage query: end of the realtime (publication) window, YYYY-MM-DD. See realtime_start.",
+  "type": "string"
+}
    • addedInput schema / properties / realtime_start
      Added value: +{
+  "description": "ALFRED vintage query: start of the realtime (publication) window, YYYY-MM-DD. Use with realtime_end for a custom vintage range; use `as_of` for the common single-date case. Omit for the default latest-revised behavior.",
+  "type": "string"
+}
    • addedOutput schema / properties / vintage
      Added value: +{
+  "description": "Present only when the caller passed as_of/realtime_start/realtime_end. The resolved vintage query.",
+  "properties": {
+    "as_of": {
+      "description": "The as_of date the caller passed, if any.",
+      "type": "string"
+    },
+    "realtime_end": {
+      "description": "The realtime_end actually sent to FRED.",
+      "type": "string"
+    },
+    "realtime_start": {
+      "description": "The realtime_start actually sent to FRED.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  2. Changed1 schema field changed
    • 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"
+  }
+]
  3. Changed14 schema fields changed
    • 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"
+]
  4. Changed1 schema field changed
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "Max observations, newest first (1-100000, default 20)",
+  "type": "number"
+}
  5. Changed1 schema field changed
    • 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"
+  }
+]
  6. Changed1 schema field changed
    • 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"
+  }
+]
  7. Changed1 schema field changed
    • 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"
+  }
+]
  8. Changed1 schema field changed
    • 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"
+  }
+]
  9. Changed1 schema field changed
    • 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)."
  10. Changed1 schema field changed
    • 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"
+}
  11. Changed1 schema field changed
    • 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"
+  }
+]
  12. First observed

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real value with failure behavior (nonexistent IDs return 400 'the series does not exist') and data provenance/granularity caveats. It does not discuss rate limits, pagination, or revision behavior, which is partly covered by the as_of/realtime schema fields rather than the description.

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?

Front-loaded with the core capability, then routing guidance, then the ID-guessing pitfall — a sensible order with no filler about the API key or generic pleasantries. Slightly long, and the mortgage-rate vs. homeownership-rate aside is marginally tangential, but it does preempt a plausible confusion.

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?

An output schema exists so return shape needn't be explained (it does so only in one clause: dates + values + units). With 11 parameters fully documented in the schema, the description's remaining burden is routing and failure modes, both of which it covers thoroughly.

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

Parameters3/5

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

Schema coverage is 100% and the schema descriptions are already detailed (units codes, frequency codes, as_of semantics), so the baseline is 3. The description adds semantic guidance for series_id — what an ID represents, worked examples, and the warning that guessed IDs fail — but says nothing about limit, sort_order, frequency, or vintage parameters beyond the schema.

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?

States a specific verb and resource (retrieve historical time-series from FRED) plus the data's granularity (country/state/metro aggregates at monthly or quarterly frequency) and concrete example series IDs. An agent can immediately tell this apart from fred_series_info (metadata), fred_search (ID lookup) or worldbank_get_indicator (non-US macro).

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 routing in three directions: use for US macro/Fed/metro indicator questions, do NOT pattern-match non-US codes like DEUUNRATE (they 400), use worldbank_get_indicator for foreign macro, and call fred_search if the series ID is unknown. Both the inclusion and exclusion criteria are named with their alternatives.

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

All Fred toolsInspect
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.

Resources