REST reference

Macro

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

Paths are relative to https://api.agentdatasets.com. Every endpoint mirrors an MCP tool over the same service layer — the tool catalog documents the same operations for MCP clients.

GET/v1/macro/calendar

Calendar

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

Parameters

Name	Type	Required	Default	Constraints	Description
start	string (date) \| null	No	—	—	First UTC day of the window, inclusive (YYYY-MM-DD). Defaults to today.
end	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	"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	integer	No	50	min 1, max 200	Scheduled occurrences to return, soonest first
cursor	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. Optional parameters are in the table above.

[ BASH ]

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

Response

200 Successful Response · expand a branch to see its fields.

dataMacroCalendarDatarequiredThe requested window echoed back, plus the occurrences inside it.
- startstring (date)required
- endstring (date)required
- source"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"nullable
- eventsarray<MacroCalendarEvent>required
  - source"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"requiredOriginating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
  - release_namestringrequired
  - scheduled_atstring (date-time)required
  - scheduled_endstring (date-time)nullable
  - period_labelstringnullable
  - status"scheduled" | "tentative"requiredHow 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.
  - urlstringnullable
  - attributionstringnullable
  - series_keysarray<string>default []
  - as_ofstring (date-time)required
metaMetarequiredResult-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.
- sourcestringrequired
- as_ofstring (date-time) | string (date)nullable
paginationPaginationnullable
- limitintegerrequired
- has_morebooleanrequired
- next_cursorstringnullable

GET/v1/macro/recent-updates

Recent Updates

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

Parameters

Name	Type	Required	Default	Constraints	Description
since	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	"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	integer	No	100	min 1, max 500	Updated series rows to return, newest first
cursor	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. Optional parameters are in the table above.

[ 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 · expand a branch to see its fields.

dataMacroRecentUpdatesDatarequiredThe 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.
- sincestring (date-time)required
- source"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"requirednullable
- updatesarray<MacroSeriesUpdate>required
  - series_keystringrequired
  - source"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"requiredOriginating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
  - titlestringrequired
  - unitsstringrequired
  - currencystringrequirednullable
  - frequency"daily" | "weekly" | "monthly" | "quarterly" | "annual"required
  - seasonal_adjustment"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"requiredSpelled out rather than "SA"/"NSA" — these values land verbatim in agent-facing payloads, where self-describing beats terse.
  - geographystringrequired
  - updated_atstring (date-time)required
  - latest_observationSeriesObservationrequiredOne 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).
    periodstring (date)required
    period_type"date" | "month" | "quarter" | "year" | "fiscal_year" | "fiscal_quarter"requiredWhat 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).
    valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
    as_ofstring (date-time)required
metaMetarequiredResult-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.
- sourcestringrequired
- as_ofstring (date-time) | string (date)nullable
paginationPaginationnullable
- limitintegerrequired
- has_morebooleanrequired
- next_cursorstringnullable

GET/v1/macro/search

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

Parameters

Name	Type	Required	Default	Constraints	Description
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	integer	No	10	min 1, max 50	Max ranked matches to return

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]

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

Response

200 Successful Response · expand a branch to see its fields.

dataMacroSearchDatarequiredThe envelope ``data`` for discovery: the echoed ``query`` plus the ranked ``matches`` (best first).
- querystringrequired
- matchesarray<MacroSeriesMatch>required
  - series_keystringrequired
  - source"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"requiredOriginating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
  - titlestringrequired
  - descriptionstringrequirednullable
  - unitsstringrequired
  - currencystringrequirednullable
  - frequency"daily" | "weekly" | "monthly" | "quarterly" | "annual"required
  - seasonal_adjustment"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"requiredSpelled out rather than "SA"/"NSA" — these values land verbatim in agent-facing payloads, where self-describing beats terse.
  - geographystringrequired
  - scorenumberrequired
  - match_reason"series_key" | "title" | "keyword"requiredWhere 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_ofstring (date-time)required
metaMetarequiredResult-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.
- sourcestringrequired
- as_ofstring (date-time) | string (date)nullable
paginationPaginationnullable
- limitintegerrequired
- has_morebooleanrequired
- next_cursorstringnullable

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

Name	Type	Required	Default	Constraints	Description
series_key	string	Yes	—	—	Exact catalog series key, e.g. treasury_yield_10y or fed_funds_target_range_upper
start	string (date) \| null	No	—	—	Inclusive start of the observation period (YYYY-MM-DD)
end	string (date) \| null	No	—	—	Inclusive end of the observation period (YYYY-MM-DD)
limit	integer	No	100	min 1, max 500	Observations to return, newest first
cursor	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	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. Optional parameters are in the table above.

[ 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 · expand a branch to see its fields.

dataMacroSeriesDatarequiredThe 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_keystringrequired
- source"treasury" | "bls" | "bea" | "ecb" | "frb" | "usaspending" | "eurostat" | "census"requiredOriginating agencies only — never FRED (CLAUDE.md hard rule; its ToU prohibits storing or DB-incorporating its content).
- titlestringrequired
- descriptionstringrequirednullable
- unitsstringrequired
- currencystringrequirednullable
- frequency"daily" | "weekly" | "monthly" | "quarterly" | "annual"required
- seasonal_adjustment"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"requiredSpelled out rather than "SA"/"NSA" — these values land verbatim in agent-facing payloads, where self-describing beats terse.
- geographystringrequired
- license_tagstringrequired
- releaseMacroReleaseInforequirednullable
  - namestringrequired
  - schedule_urlstringrequirednullable
- startstring (date)requirednullable
- endstring (date)requirednullable
- observationsarray<SeriesObservation>required
  - periodstring (date)required
  - period_type"date" | "month" | "quarter" | "year" | "fiscal_year" | "fiscal_quarter"requiredWhat 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).
  - valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
  - as_ofstring (date-time)required
metaMacroSeriesMetarequiredRead 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.
- sourcestringrequired
- as_ofstring (date-time) | string (date)nullable
- point_in_timebooleandefault false
- as_known_atstring (date-time)nullable
- vintage_coverage_startstring (date-time)nullable
paginationPaginationnullable
- limitintegerrequired
- has_morebooleanrequired
- next_cursorstringnullable

GET/v1/macro/calendar#

Parameters

Example request

Response

GET/v1/macro/recent-updates#

Parameters

Example request

Response

GET/v1/macro/search#

Parameters

Example request

Response

GET/v1/macro/series#

Parameters

Example request

Response

GET/v1/macro/calendar

GET/v1/macro/recent-updates

GET/v1/macro/search

GET/v1/macro/series