# macro_get_series Observations for one macro series, newest first, with interpretive context. | Field | Value | | --- | --- | | Category | Macro (`macro`) | | Exposure | public | | MCP tool | `macro_get_series` | | Documentation | https://www.agentdatasets.com/docs/tools/macro_get_series | ## Description Observations for one macro series, newest first, with interpretive context. The result is the shared envelope. `data` holds the series metadata you need to read the numbers — `series_key`, `source`, `title`, `units` (e.g. "percent", "USD", "index 1982-84=100"), `currency`, `frequency`, `seasonal_adjustment`, `geography`, `license_tag`, and the `release` (name + schedule_url, or null for continuous datasets) — plus the echoed `start`/`end` and the bounded `observations` list. Each observation has `period` (the first day of the represented span), `period_type` (`date`/`month`/`quarter`/`year`/`fiscal_year`/`fiscal_quarter`), `value` (an exact decimal serialized as a JSON string), and `as_of` (when we ingested it). `meta` holds `source` (the originating agency), `as_of` (the freshest value on this page), and the point-in-time mode fields; `pagination` holds the cursor paging state. Set `as_known_at` to answer as if asked at that instant: each observation comes from the newest vintage ingested at or before it. Omit it for today's latest view. Point-in-time metadata echoes the timestamp and names the series' `vintage_coverage_start`. The default is 100 observations and the maximum is 500. To page, pass `pagination.next_cursor` back as `cursor`; when `pagination.has_more` is false, `next_cursor` is null and you have reached the oldest observation in the window. For a long daily series prefer narrowing `start`/`end` (or a coarser-frequency series key from macro_search_series) over paging through years of rows. U.S. agency data is public domain; Eurostat data (`license_tag: cc-by-4.0`) requires attribution when republished — cite "Source: Eurostat, © European Union, CC BY 4.0". Both are publicly redistributable, unlike the price tools. Errors carry a machine `code`: `unknown_entity` for a series_key we do not hold (with `Did you mean: …?` suggestions when a close key exists — or call macro_search_series), `out_of_coverage` when `as_known_at` predates the series' vintage capture, and `bad_parameter` for input the schema can't reject (a malformed cursor or naive `as_known_at`). Example: `macro_get_series(series_key="treasury_yield_10y", start="2025-01-01", end="2025-01-31", as_known_at="2026-06-15T12:00:00Z")`. ## Parameters Input schema advertised to MCP clients and mirrored by the REST query string. | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | series_key | input | `string` | yes | — | — | The exact catalog series key, e.g. 'treasury_yield_10y', 'cpi_all_items_sa', 'fed_funds_target_range_upper'. For a topic rather than an exact key, call macro_search_series first — this tool does not fuzzy-match. | | start | input | `string (date) \| null` | no | null | — | Inclusive start of the observation period (YYYY-MM-DD). Omit for no lower bound (newest observations first). | | end | input | `string (date) \| null` | no | null | — | Inclusive end of the observation period (YYYY-MM-DD). Omit for no upper bound. | | limit | input | `integer` | no | 100 | min 1, max 500 | Observations to return, newest first (1–500). | | cursor | input | `string \| null` | no | null | — | Opaque pagination cursor from a previous response's `pagination.next_cursor`; keep `start`/`end`/`as_known_at` constant while paging. Omit to start from the newest observation. | | as_known_at | input | `string (date-time) \| null` | no | null | — | Optional point-in-time knowledge timestamp: an RFC 3339 timestamp with a timezone offset. For each observation, return the newest vintage ingested at or before this instant. A timestamp earlier than the series' vintage coverage raises `out_of_coverage`; a future timestamp returns the current view in point-in-time mode. Keep `start`/`end`/`as_known_at` constant while paging. Omit for today's latest view. | ## Provenance - `bea` — U.S. Bureau of Economic Analysis, NIPA table lines: GDP (growth/nominal/chained), personal consumption expenditures, personal income, PCE price indexes (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md - `bls` — U.S. Bureau of Labor Statistics, CPI (headline/core, seasonally adjusted/not adjusted), PPI final demand, unemployment, labor-force participation, nonfarm payrolls, average hourly earnings (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md - `ecb` — European Central Bank, Ten curated ECB key-interest-rate, €STR, and euro-area AAA central-government yield-curve spot-rate series (ECB information reuse terms (ecb-reuse)). See https://www.agentdatasets.com/docs/attribution.md - `eurostat` — Eurostat, Curated euro-area price, activity and labour series (Creative Commons Attribution 4.0 International (CC BY 4.0)). See https://www.agentdatasets.com/docs/attribution.md - `frb` — Board of Governors of the Federal Reserve System, Curated H.15 and PRATES policy/market rates plus FOMC federal-funds target-range levels (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md - `treasury` — U.S. Department of the Treasury, Daily par yield curve (11 tenors), Debt to the Penny, and average interest rates on Treasury securities (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md - `usaspending` — U.S. Department of the Treasury, USAspending.gov, Agency and government-wide federal contract and assistance obligation totals by fiscal year and fiscal quarter (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md Dataset registry: `macro_bea`, `macro_bls`, `macro_ecb`, `macro_eurostat`, `macro_frb`, `macro_treasury`, `macro_usaspending`.