---
title: "The forward economic calendar"
method: GET
path: "/v1/calendar"
tags: ["Economic data"]
---

# The forward economic calendar

`GET /v1/calendar`

## Request

- Base URL: `https://api.helious.io`
- URL: `https://api.helious.io/v1/calendar`
- Auth: one of:
  - none
  - HTTP bearer

Economic releases with forecasts, prior values and the actual once it prints, plus Fed speakers and auction times. Windowed: defaults to yesterday through the next 7 days, trimmed to the fields an answer is built from. Widen days_back / days_ahead for more, or filter by country. On the free tiers a print stays held for 60 minutes after it lands, the same hour /v1/feed holds the release card: its row shows status delayed and reveal_at in place of the actual. Paid plans see it live.

## Query parameters

- `days_back` integer
- `days_ahead` integer
- `country` string
- `limit` integer
- `fresh` boolean

## Response `200`

summary + source + data + meta envelope

- Envelope: Every /v1 response. `summary` states the answer as one plain-English sentence and `source` says who to credit for it, both before the raw `data`, so the finished claim is the first thing a reader meets.
  - `summary` string: The answer as a sentence, with the numbers in it. Identical to the sentence the matching MCP tool returns.
  - `source` object: Who to credit and where a reader can check the number.
    - `name` string
    - `url` string, uri: The Helious page backing this answer.
    - `cite_as` string
    - `attribution` string
    - `live` string: How current these numbers are on YOUR plan, and how to ask for them again. Says the data is live only on a tier that serves it live.
  - `data` object: The dataset itself.
  - `meta` object: When it was true, and what your plan allows.
  - `plan_limit` object: Present only when your plan moved the window. Says this is a plan limit rather than missing data, what Helious holds behind it, and the exact step to relay to the person you work for.

## Other responses

- `429`: Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.

## Changes

- **2026-10-20** `06bada17ad7a`: 2 info
  - added the new optional `query` request parameter `fresh`
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/helious/apis/helious-public-api/changes/v1/calendar/get.md)

---

[API](https://skmtc.dev/helious/apis/helious-public-api.md) · [All operations](https://skmtc.dev/helious/apis/helious-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/helious/apis/helious-public-api/revisions/06bada17ad7a?raw)