--- title: "Get Macro Series" method: GET path: "/api/v1/macro/{country}/{section}" tags: ["Economics"] --- # Get Macro Series `GET /api/v1/macro/{country}/{section}` Fetch a single macro time-series from FRED. country: ISO-2 lowercase code (us, eu, gb, jp) section: indicator key - see GET /api/macro/catalog for full list Query parameters: start - observation start YYYY-MM-DD (activates range mode) end - observation end YYYY-MM-DD last_n - return N most recent observations (default: catalog default_last_n) limit - deprecated alias for last_n transform - comma-separated transforms; must match series unit_type: index/money: mom_pct, yoy_pct, qoq_ann_pct rate_pct daily: dod_bps, wow_bps rate_pct monthly: mom_pp, yoy_pp spread_pct: dod_bps, wow_bps count: mom_abs, yoy_abs Legacy aliases: mom → mom_pct, yoy → yoy_pct, 3m_ann → qoq_ann_pct order - "desc" (newest first, default) or "asc" Mode semantics: last_n mode - returns the N most recent observations (default when no start given) range mode - returns all observations in [start, end] up to max_last_n cap Response is cached in-memory (TTL by frequency): daily series - 6 hours monthly series - 24 hours quarterly series - 72 hours Anomalous results (mid-series nulls in monthly/quarterly) are not cached. ## Path parameters - `country` string, required — Country code (ISO 3166-1 alpha-2/alpha-3) or slug. - `section` string, required — Report section. ## Query parameters - `start` string, nullable — Start date (YYYY-MM-DD). - `end` string, nullable — End date (YYYY-MM-DD) or pagination end. - `last_n` integer, nullable — Return last N observations per series. - `limit` integer, nullable — Maximum number of records to return. - `transform` string, nullable — Data transformation (lin, chg, pch). - `order` string — Sort order. ## Response `200` FRED macro time series for the given country and section with optional transforms. - EnvelopeMacroResponse - `data` MacroResponse, required — Response shape for GET /api/macro/{country}/{section}. - `series` MacroSeriesInfo, required — Metadata about the FRED series returned in the series block. - `country` string, required — Country code or name. - `section` string, required — Catalog section identifier (e.g. cpi, unrate). - `fred_series_id` string, required — FRED series identifier (e.g. GDPC1, UNRATE). - `title` string, required — Display title. - `units` string, required — Units of measure. - `frequency` string, required — Observation frequency (daily, weekly, monthly, quarterly, annual). - `seasonal_adjustment` string, required — Seasonal adjustment label from FRED. - `source` string, required — Upstream data source identifier. - `unit_type` string, required — Catalog unit_type (index, level, money, rate_pct, spread_pct, count). - `last_updated` string, nullable — Last-update timestamp. - `data` MacroDataPoint[], required — Primary payload. - `date` string, required — Observation date (YYYY-MM-DD). - `value` number, nullable, required — Numeric or string value. - `value_mom_pct` number, nullable — Month-over-month percent change. - `value_yoy_pct` number, nullable — Year-over-year percent change. - `value_qoq_ann_pct` number, nullable — Quarter-over-quarter annualized percent change. - `value_dod_bps` number, nullable — Day-over-day change in basis points. - `value_wow_bps` number, nullable — Week-over-week change in basis points. - `value_mom_pp` number, nullable — Month-over-month change in percentage points. - `value_yoy_pp` number, nullable — Year-over-year change in percentage points. - `value_mom_abs` number, nullable — Month-over-month absolute change. - `value_yoy_abs` number, nullable — Year-over-year absolute change. - `meta` MacroMeta, required — Response metadata for single-series and per-series in /multi. - `requested_range` MacroRequestedRange, required — What the caller asked for (null if not provided). - `start` string, nullable, required — Start of the data range or pagination cursor. - `end` string, nullable, required — End of the data range or time window. - `effective_range` MacroEffectiveRange, required — Actual date span of the observations returned. - `start` string, nullable, required — Start of the data range or pagination cursor. - `end` string, nullable, required — End of the data range or time window. - `mode` string, required — Query mode: range or last_n. - `last_n` integer, nullable, required — last_n value when mode == last_n. - `order` string, required — Sort order (asc or desc). - `count` integer, required — Number of items in this result set. - `last_observation_date` string, nullable, required — Newest non-null observation date. - `transforms_applied` string[], required — Transforms applied to the observations. - `calculation_lookback_points` integer, nullable, required — Max lookback observations used for transforms. - `cache` MacroCacheInfo, required - `hit` boolean, required — Cache hit flag. - `fetched_at` string, required — Cache fetched_at timestamp. - `ttl_seconds` integer, required — Cache TTL in seconds. - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope. - `endpoint` string, required — Requested endpoint path. - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request. - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced. - `provider` string, required — API name and version. - `source` string, nullable — Identifier of the primary upstream source used for this response. - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response. - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data. - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried. - `cached` boolean, nullable — True when this response was served from the internal cache. - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data. ## Other responses - `401` — Missing or invalid `x-api-key` header. - `422` — Validation Error - `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window. - `503` — Upstream source is temporarily unavailable. Retry after a short delay. --- [API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4e2740743eb4/schema)