---
title: "Macroeconomic series (CPI, inflation, GDP, unemployment, policy rate, treasury yield, retail sales, payrolls, PMI, money supply) by country. Returns a normalized SeriesPoint page, most recent first."
method: POST
path: "/v2/ops/finance.macro.series"
tags: ["finance"]
---

# Macroeconomic series (CPI, inflation, GDP, unemployment, policy rate, treasury yield, retail sales, payrolls, PMI, money supply) by country. Returns a normalized SeriesPoint page, most recent first.

`POST /v2/ops/finance.macro.series`

## Request

- Base URL: `https://api.agentkey.app`
- URL: `https://api.agentkey.app/v2/ops/finance.macro.series`
- Auth: HTTP bearer

Pick a series and a country (ISO alpha-2, default US). interval=auto takes the series' native frequency; an explicit interval routes to a provider that reports it. maturity applies to treasury_yield only. Verified for China (cpi, inflation, gdp, pmi, money_supply) and the US (every series but pmi / money_supply); World Bank and Eurostat series wait on network / engine fixes.

Fixed price: 0.1 credits per successful call, whichever provider serves it.

## Request body

- object
  - `country` string: ISO 3166-1 alpha-2 of the economy (US, CN, DE, JP).
  - `fields` string[]: Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"].
  - `include_raw` boolean: Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB).
  - `interval` 'auto' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'semiannual' | 'annual': Reporting frequency; auto = the series' native frequency at the provider.
  - `limit` integer: Maximum number of observations to return.
  - `maturity` '3month' | '2year' | '5year' | '7year' | '10year' | '30year': Bond maturity for treasury_yield.
  - `provider` string: Shorthand for routing.only = [provider].
  - `routing` Routing: Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider.
    - `allow_fallbacks` boolean: false = try only the first eligible provider.
    - `only` string[]: Restrict to these providers.
    - `order` string[]: Providers to try first, in order.
    - `strategy` 'auto': How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order.
  - `series` 'cpi' | 'inflation' | 'gdp' | 'unemployment' | 'policy_rate' | 'treasury_yield' | 'retail_sales' | 'payrolls' | 'pmi' | 'money_supply', required: cpi = price index level; inflation = CPI change in percent year on year; gdp = output in the vendor's unit; unemployment = rate in percent; policy_rate = central bank rate; treasury_yield = government bond yield; retail_sales, payrolls, pmi, money_supply as the national statistics office publishes them.

## Response `200`

Success envelope

- SeriesPointPageEnvelope: Success envelope whose data is a SeriesPointPage.
  - `attempts` Attempt[], required
    - `error_type` string: validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error
    - `provider` string, required: Provider slug.
    - `refunded` boolean: true when the reservation for this attempt was refunded.
    - `status` integer, required: HTTP status AgentKey mapped this attempt to (200 on success).
    - `took_ms` integer, required
    - `tool` string, required: Registry tool name (Provider/operation) that was called.
    - `upstream_status` integer: The provider's real HTTP status; absent when nothing was received.
  - `credits_charged` number, required: Credits charged for this call (the method's fixed price).
  - `data` object, required: One page of observations, most recent first.
    - `items` SeriesPoint[], required
      - `country` string, required: ISO 3166-1 alpha-2 of the economy.
      - `date` string, date, nullable, required: First calendar day of the observation period, YYYY-MM-DD (2025-07-01 for 2025 Q3, 2025-01-01 for the year 2025).
      - `interval` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'semiannual' | 'annual' | 'null', nullable, required: Reporting frequency of this series at this provider.
      - `series` string, required: Series id as requested (cpi, gdp, unemployment …).
      - `unit` string, nullable, required: Unit as the vendor states it (percent, index 1982-1984=100, billions of dollars, 亿元 …).
      - `value` number, nullable, required: Observed value in `unit`.
    - `next_cursor` string, nullable, required: Opaque cursor for the next page; null when exhausted or the provider cannot page.
  - `op` string, required: Method name.
  - `op_version` integer, required: Method version that served the call.
  - `provider` string, required: Provider that actually served the call.
  - `raw` unknown
  - `raw_truncated` boolean
  - `request_id` string, required: Correlation id; quote it in support requests.
  - `took_ms` integer, required
  - `unsupported_fields` string[], required: Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'.

## Other responses

- `400`: Validation error (unknown field, bad cursor, bad routing)
- `402`: Insufficient credits
- `404`: Not found (method, or upstream object)
- `429`: Rate limited upstream
- `502`: All providers failed
- `504`: Timed out

---

[API](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods.md) - [All operations](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/revisions/a7cf5b682fdd?raw)