<!-- Agent Datasets docs · Macro REST endpoints · canonical: https://www.agentdatasets.com/docs/rest/macro · rendered from https://www.agentdatasets.com -->

# Macro REST endpoints

US macroeconomic time series — Treasury yields, BLS employment and inflation measures, and BEA national accounts.

4 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients.

## GET /v1/macro/calendar

Calendar

Scheduled official macro releases in a date window, soonest first.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| start | query | `string (date) \| null` | no | — | — | First UTC day of the window, inclusive (YYYY-MM-DD). Defaults to today. |
| end | query | `string (date) \| null` | no | — | — | Last UTC day of the window, inclusive (YYYY-MM-DD). Defaults to start + 14 days; the window may span at most 93 days. |
| source | query | `"treasury" \| "bls" \| "bea" \| "ecb" \| "frb" \| "usaspending" \| "eurostat" \| "census" \| null` | no | — | — | Optional agency filter: bls, bea, census, frb (FOMC meetings and the H.15/H.4.1/H.8/G.17/G.19 statistical releases), or ecb (statistical calendar and Governing Council monetary policy meetings); omit for all |
| limit | query | `integer` | no | 50 | min 1, max 200 | Scheduled occurrences to return, soonest first |
| cursor | query | `string \| null` | no | — | — | Opaque pagination cursor from a previous response's pagination.next_cursor; keep start/end/source constant while paging. |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/macro/calendar"
```

### Response

`200` Successful Response — `MacroCalendarResult`.

- `data` `MacroCalendarData` (required) — The requested window echoed back, plus the occurrences inside it.
  - `start` `string (date)` (required)
  - `end` `string (date)` (required)
  - `source` `"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census" | null`
  - `events` `array<MacroCalendarEvent>` (required)
    - `source` `"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"` (required) — Originating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
    - `release_name` `string` (required)
    - `scheduled_at` `string (date-time)` (required)
    - `scheduled_end` `string (date-time) | null`
    - `period_label` `string | null`
    - `status` `"scheduled" | "tentative"` (required) — How firm a scheduled release occurrence is. ``TENTATIVE`` covers the sources that say so in their own words: ECB statistical-calendar rows flagged "Tentative" and Federal Reserve statistical releases whose note says the publication date is approximate. Everything else is ``SCHEDULED``. Occurrences are never deleted once published — a moved date updates the same row in place.
    - `url` `string | null`
    - `attribution` `string | null`
    - `series_keys` `array<string>`
    - `as_of` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/macro/recent-updates

Recent Updates

Updated macro series since a timestamp, newest first, bounded and paged.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| since | query | `string (date-time)` | yes | — | — | RFC 3339 timestamp with timezone offset; returns series updated strictly after this timestamp. In a query string prefer the Z suffix (2026-07-01T00:00:00Z) — an unencoded '+HH:MM' offset decodes as a space; percent-encode the plus as %2B. |
| source | query | `"treasury" \| "bls" \| "bea" \| "ecb" \| "frb" \| "usaspending" \| "eurostat" \| "census" \| null` | no | — | — | Optional agency filter: treasury, bls, bea, ecb, frb (Federal Reserve Board H.15/PRATES policy and market rates, H.4.1 balance-sheet levels, H.8 bank credit and deposits, G.17/G.19 activity and credit, and SLOOS credit conditions), usaspending, or eurostat; omit for all sources |
| limit | query | `integer` | no | 100 | min 1, max 500 | Updated series rows to return, newest first |
| cursor | query | `string \| null` | no | — | — | Opaque pagination cursor from a previous response's pagination.next_cursor; keep since/source constant while paging. |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/macro/recent-updates?since=2024-01-01T00%3A00%3A00Z"
```

### Response

`200` Successful Response — `MacroRecentUpdatesResult`.

- `data` `MacroRecentUpdatesData` (required) — The envelope ``data`` for recent updates: the echoed strictly-after ``since`` boundary, the optional agency ``source`` filter (``None`` means all sources), and the newest-first ``updates`` page.
  - `since` `string (date-time)` (required)
  - `source` `"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census" | null` (required)
  - `updates` `array<MacroSeriesUpdate>` (required)
    - `series_key` `string` (required)
    - `source` `"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"` (required) — Originating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
    - `title` `string` (required)
    - `units` `string` (required)
    - `currency` `string | null` (required)
    - `frequency` `"daily" | "weekly" | "monthly" | "quarterly" | "annual"` (required)
    - `seasonal_adjustment` `"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"` (required) — Spelled out rather than "SA"/"NSA" — these values land verbatim in agent-facing payloads, where self-describing beats terse.
    - `geography` `string` (required)
    - `updated_at` `string (date-time)` (required)
    - `latest_observation` `SeriesObservation` (required) — One value of one series for one period. ``period`` anchors the span (the date itself for daily/weekly series, the first day of the month/quarter/year otherwise — see ``period_type``); ``value`` is an exact decimal serialized as a JSON string; ``as_of`` is when we last ingested this value (a restatement refreshes it).
      - `period` `string (date)` (required)
      - `period_type` `"date" | "month" | "quarter" | "year" | "fiscal_year" | "fiscal_quarter"` (required) — What kind of span an observation's ``period`` date anchors. ``DATE`` covers point-in-time and week-ending observations; the others anchor to the first day of their span (enforced by a check constraint).
      - `value` `string` (required)
      - `as_of` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/macro/search

Search

Ranked macro-series matches for a topic/key/keyword query, best first.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| query | query | `string` | yes | — | — | Macro topic, series-key fragment, or keyword across Treasury, BLS, BEA, ECB policy/€STR/yield curves, Federal Reserve Board H.15/PRATES policy and market rates, H.4.1 balance-sheet levels, H.8 bank credit and deposits, G.17/G.19 activity and credit, SLOOS credit conditions, USAspending agency obligations, and Eurostat indicators |
| limit | query | `integer` | no | 10 | min 1, max 50 | Max ranked matches to return |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/macro/search?query=QUERY"
```

### Response

`200` Successful Response — `MacroSeriesSearchResult`.

- `data` `MacroSearchData` (required) — The envelope ``data`` for discovery: the echoed ``query`` plus the ranked ``matches`` (best first).
  - `query` `string` (required)
  - `matches` `array<MacroSeriesMatch>` (required)
    - `series_key` `string` (required)
    - `source` `"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"` (required) — Originating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
    - `title` `string` (required)
    - `description` `string | null` (required)
    - `units` `string` (required)
    - `currency` `string | null` (required)
    - `frequency` `"daily" | "weekly" | "monthly" | "quarterly" | "annual"` (required)
    - `seasonal_adjustment` `"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"` (required) — Spelled out rather than "SA"/"NSA" — these values land verbatim in agent-facing payloads, where self-describing beats terse.
    - `geography` `string` (required)
    - `score` `number` (required)
    - `match_reason` `"series_key" | "title" | "keyword"` (required) — Where a search query matched, so an agent can see why a series ranked. ``series_key`` — the stable id matched (exact/prefix/substring); ``title`` — the human title matched; ``keyword`` — every query token appears somewhere in the series' metadata (title, description, units, geography, source).
    - `as_of` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/macro/series

Series

Observations for one macro series, newest first, bounded and paged.

``as_known_at`` selects the newest vintage known by that instant; omitting
it preserves today's latest view.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| series_key | query | `string` | yes | — | — | Exact catalog series key, e.g. treasury_yield_10y or fed_funds_target_range_upper |
| start | query | `string (date) \| null` | no | — | — | Inclusive start of the observation period (YYYY-MM-DD) |
| end | query | `string (date) \| null` | no | — | — | Inclusive end of the observation period (YYYY-MM-DD) |
| limit | query | `integer` | no | 100 | min 1, max 500 | Observations to return, newest first |
| cursor | query | `string \| null` | no | — | — | 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 | query | `string (date-time) \| null` | no | — | — | 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. |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/macro/series?series_key=SERIES_KEY"
```

### Response

`200` Successful Response — `MacroSeriesResult`.

- `data` `MacroSeriesData` (required) — The envelope ``data`` for one series' observations. Carries the full interpretive context inline (units, currency, frequency, seasonal adjustment, geography, license, release) so an agent can read the ``observations`` without a second lookup, mirroring how the statements tools inline company identity. ``start``/``end`` echo the requested window (both ``None`` when unconstrained); ``observations`` is the bounded, newest-first page.
  - `series_key` `string` (required)
  - `source` `"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"` (required) — Originating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
  - `title` `string` (required)
  - `description` `string | null` (required)
  - `units` `string` (required)
  - `currency` `string | null` (required)
  - `frequency` `"daily" | "weekly" | "monthly" | "quarterly" | "annual"` (required)
  - `seasonal_adjustment` `"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"` (required) — Spelled out rather than "SA"/"NSA" — these values land verbatim in agent-facing payloads, where self-describing beats terse.
  - `geography` `string` (required)
  - `license_tag` `string` (required)
  - `release` `MacroReleaseInfo | null` (required)
    - `name` `string` (required)
    - `schedule_url` `string | null` (required)
  - `start` `string (date) | null` (required)
  - `end` `string (date) | null` (required)
  - `observations` `array<SeriesObservation>` (required)
    - `period` `string (date)` (required)
    - `period_type` `"date" | "month" | "quarter" | "year" | "fiscal_year" | "fiscal_quarter"` (required) — What kind of span an observation's ``period`` date anchors. ``DATE`` covers point-in-time and week-ending observations; the others anchor to the first day of their span (enforced by a check constraint).
    - `value` `string` (required)
    - `as_of` `string (date-time)` (required)
- `meta` `MacroSeriesMeta` (required) — Read mode + vintage coverage for ``macro_get_series``. Latest reads keep the defaults. Point-in-time reads echo the effective knowledge timestamp and the earliest instant the series can answer honestly, so an agent can distinguish time travel from today's view.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `point_in_time` `boolean`
  - `as_known_at` `string (date-time) | null`
  - `vintage_coverage_start` `string (date-time) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json