Economic calendar API

One call returns the economic calendar with the forecast, the previous and the actual for every event, and, once a release prints, a surprise score in standard deviations against that release's own history. CPI, payrolls, PMIs, auctions and central bank events across the US, the euro area, the UK and Japan. The first call is free and needs no key.

Most calendar APIs stop at the actual. Helious adds the reading: a sigma value, so a CPI miss and a payrolls beat sit on the same ruler, and a word for it, from MAJOR MISS to MAJOR BEAT. Ask for days ahead to plan the week, or days back to see what already printed and how big each surprise was.

Your first call

No account and no key. Paste the line below and run it.

Terminal

curl "https://api.helious.io/v1/calendar?days_back=1&days_ahead=7&country=US"

Python

import requests

r = requests.get("https://api.helious.io/v1/calendar",
                 params={"days_back": 1, "days_ahead": 0, "country": "US"}, timeout=15)
for e in r.json()["data"]["events"]:
    if e["status"] == "printed" and "sigma" in e:
        print(e["title"], e["actual"], e["forecast"], e["sigma"], e["surprise"])

What comes back

Every answer opens with summary, a finished sentence a person or an AI can quote as it is, then source, data and meta.

What /v1/calendar returned on 23 Oct 2026, trimmed for reading

{
  "summary": "136 events on the Helious economic calendar between 22 Oct 2026 16:22 UTC and 30 Oct 2026 16:22 UTC: 27 have already printed and 109 are still to come. Next up: Baker Hughes US Oil Rig Count at 23 Oct 2026 17:00 UTC.",
  "data": {
    "events": [
      {
        "datetime_utc": "2026-10-23T13:45:00+00:00",
        "title": "S&P Global Manufacturing PMI",
        "country": "US",
        "impact": "High",
        "type": "economic",
        "forecast": "55.6",
        "previous": "55.9",
        "actual": "56",
        "status": "printed",
        "surprise": "IN LINE",
        "sigma": 0.44
      },
      {
        "datetime_utc": "2026-10-23T14:00:00+00:00",
        "title": "Michigan Consumer Sentiment Index",
        "country": "US",
        "impact": "Medium",
        "type": "economic",
        "forecast": "46.3",
        "previous": "46.3",
        "actual": "48",
        "status": "printed",
        "surprise": "SLIGHT BEAT",
        "sigma": 0.81
      },
      {
        "datetime_utc": "2026-10-22T23:01:00+00:00",
        "title": "GB: GfK Consumer Confidence",
        "country": "GB",
        "impact": "Medium",
        "type": "economic",
        "forecast": "-15",
        "previous": "-13",
        "actual": "-24",
        "status": "printed",
        "surprise": "MAJOR MISS",
        "sigma": -4.5
      }
    ]
  },
  "meta": {
    "tier": "keyless",
    "history_days": 1,
    "delay_sec": 3600
  }
}

What each field means

Field	Meaning
`datetime_utc`	When the event is due, in UTC.
`forecast, previous, actual`	The consensus forecast, the prior reading and the printed number, as published.
`status`	due or printed.
`sigma`	The surprise in standard deviations against that release's own history. Positive is above forecast.
`surprise`	The sigma in words, from MAJOR MISS through IN LINE to MAJOR BEAT.
`impact`	High, Medium or Low: how much the event usually moves markets.
`country`	Two-letter country or bloc. Filter with country=US, EU, GB or JP.

How it compares

Trading Economics has the broadest global calendar and quotes its API on request. Benzinga and FMP sell calendar data with forecast, previous and actual fields. None of them returns a surprise score, so judging how big a miss was is left to you. Helious scores every release on print and costs nothing to start.

Helious vs the Trading Economics API

What it costs

Every plan sees the same endpoints and the same response shapes, so code written on the free tier keeps working when you upgrade. A data call is 1 credit.

Plan	Price	History	Freshness	Credits
No key	$0	1 day	1 hour behind	50 credits a month, shared by your network address
Free key	$0	7 days	1 hour behind; one call live for 5 credits with fresh=1	100 credits a month
Starter	$14.99 a month	12 months	News, prints and auctions live; market prices an hour behind	1,500 credits a month
Pro	$39.99 a month	24 months	Live, plus the live WebSocket stream	3,000 credits a month
Ultimate	$99 a month	10 years	Live, commercial use and redistribution	No cap

In an AI assistant, the same data is the get_economic_calendar tool on the MCP server. For a spreadsheet, a CSV sample of recent rows sits at helious.io/data/cpi.csv.

Questions

Is there a free economic calendar API?

Yes. GET https://api.helious.io/v1/calendar works with no key: it returns the calendar with forecast, previous and actual for each event, an hour behind, with 1 day of history. A free account key adds 7 days of history.

Which economic calendar API includes actual vs forecast?

The Helious calendar API returns forecast, previous and actual on every event, and adds sigma, the surprise in standard deviations against that release's own history, plus a word for it such as SLIGHT BEAT or MAJOR MISS.

Is the economic calendar API real time?

On Starter ($14.99 a month) and above, a release is served live the moment it prints. With no key or a free key, the calendar is an hour behind, and a free key can ask for one call live with fresh=1 for 5 credits.

Which countries does it cover?

The US in depth, plus the euro area, the UK and Japan. Pass country=US, EU, GB or JP, or leave it out for everywhere.

Can an AI assistant read the calendar?

Yes. The MCP server at https://api.helious.io/mcp exposes it as the get_economic_calendar tool, with the same answer sentence the API returns.

Financial data MCP server