Real-time economic data API

Helious is a real-time economic data API that delivers each US economic release as Helious captures it, a median of 6 seconds after publication in the week to 10 November 2026, with the actual, the consensus forecast, the previous and the surprise in standard deviations, over REST, a live WebSocket and an MCP server.

One call per series returns the latest US print with its forecast, its previous and its surprise in standard deviations, the prints before it, the consensus record and the official history. CPI, payrolls, GDP, retail sales, the PMIs, jobless claims and the rest of the tracked US series. The first call is free and needs no key.

Why Helious

• Seconds from print to API. Helious reads each US release as it publishes and measures how long that took. Over the 7 days to 10 November 2026 the median was 6 seconds across 50 releases, and nine in ten landed within 91 seconds. The live figure is at /api/seo/latency-stats.
• The reading arrives with the number. z is the surprise in standard deviations and label says it in words, so a 0.1 miss on CPI and a 50K miss on payrolls sit on one ruler.
• The history is in the same call. prints holds the captured first prints with their forecasts, consensus_history the consensus record, and official_history the published table with year-over-year rates. level_pctile places the latest level in its own history (CPI back to 1983).
• Pushed, not polled, on Pro. Pro ($39.99 a month) and Ultimate receive every print on wss://api.helious.io/v1/stream the moment it lands; Starter ($14.99) serves it live over REST.
• Free to start. The first call needs no key; every plan sees the same fields.

Every series has a slug: cpi, nonfarm-payrolls, gdp, retail-sales, jobless-claims. /v1/series lists them all. For the week's schedule across every release, read the economic calendar API; for each print pushed the moment it lands, the live stream below.

Your first call

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

curl "https://api.helious.io/v1/series/cpi"

import requests

r = requests.get("https://api.helious.io/v1/series/cpi", timeout=15)
r.raise_for_status()
d = r.json()
print(d["summary"])
for p in d["data"]["prints"]:           # inside your plan's history window
    print(p["created_at"], p["actual"], p["forecast"], p["z"], p["label"])

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.

{
  "summary": "Consumer Price Index (CPI) last printed 0.40% on 10 Nov 2026 13:30 UTC against a 0.30% forecast, previous 0.60%, a 1.25 sigma surprise. The level itself sits in the 96th percentile of the official series back to 1983. Captured live by Helious at the moment it printed.",
  "data": {
    "prints": [
      {
        "title": "Consumer Price Index (MoM): 0.40%",
        "created_at": "2026-11-10T13:30:07.696185+00:00",
        "actual": "0.40%",
        "forecast": "0.30%",
        "previous": "0.60%",
        "z": 1.25,
        "label": "ABOVE FORECAST",
        "path": "/news/rel-ev-e6e758d4df44b125/consumer-price-index-mom-0-40"
      }
    ],
    "official_history": {
      "label": "% m/m",
      "rows": [
        {
          "date": "2026-09-01",
          "value": 0.65,
          "yoy": 3.7
        }
      ]
    },
    "level_pctile": {
      "value": 0.65,
      "as_of": "2026-09-01",
      "pct": 96,
      "n": 519,
      "since": "1983-05-01"
    }
  }
}

What each field means

Live stream

One WebSocket on every plan. Delayed below Pro; live on Pro and Ultimate.

Polling catches a print on the next call. The stream pushes it: one WebSocket at wss://api.helious.io/v1/stream that sends every release the moment Helious posts it, beside the wire headlines, the price board, the NASDAQ-100 board and the daily closes. Send the same hel_ key as the Authorization: Bearer header, never in the address. With no key the socket still opens, on the delayed lane.

import asyncio, json, websockets   # websockets 14 or later

async def main():
    headers = {"Authorization": "Bearer hel_your_key_here"}
    async with websockets.connect("wss://api.helious.io/v1/stream", additional_headers=headers) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("type") == "feed":
                for item in msg["items"]:
                    if item.get("category") == "release":
                        print(item["created_at"], item["title"], item.get("text", ""))

asyncio.run(main())

A release arrives as a feed message, one item per print, with kind post and category release. The text carries the actual, the forecast, the previous and the surprise in sigma; score and direction are the Helious read for bonds, equity_score and equity_direction for stocks. For the same print as separate fields, read /v1/calendar once it lands.

{
  "type": "feed",
  "items": [
    {
      "id": "rel-ev-f58f900c2a0fd770",
      "kind": "post",
      "title": "S&P Global Services PMI: 56.1",
      "text": "S&P Global Services PMI: Actual 56.1, forecast 57.9, prev 57.9. Surprise: BELOW FORECAST by 2.0 sigma. Desk read: Bonds BULLISH · Equities BEARISH.",
      "category": "release",
      "created_at": "2026-11-04T14:45:14.050008+00:00",
      "score": 4.8,
      "direction": "BULLISH BONDS",
      "equity_score": -4.8,
      "equity_direction": "BEARISH EQUITIES",
      "topic": "data",
      "url": "https://helious.io/news/rel-ev-f58f900c2a0fd770/s-p-global-services-pmi-56-1"
    }
  ]
}

Pro ($39.99 a month) and Ultimate ($99 a month) receive the live lane: every print the moment it lands, on up to 2 connections a key on Pro and 5 on Ultimate. Every other plan runs the same socket on the delayed lane, one snapshot a minute: on Starter a print arrives on the next snapshot, and with no key or a free key an hour behind. The stream takes no credits on a paid plan; with no key or a free key the connect and each minute's snapshot take 1 credit each. The first message is a hello whose mode says which lane you are on, and the message shapes are the same on both, so code written on the delayed lane keeps working after an upgrade. Every message type is on the reference page.

How it compares

An official release gives the value without a consensus forecast or a surprise. Helious returns the print, the forecast and the surprise in one answer as it lands, from a free key up.

How the Helious API compares with other data APIs

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.

In an AI assistant, the same data is the get_series tool on the MCP server.

Questions

Is there a real-time economic data API?

Yes. GET https://api.helious.io/v1/series/{slug} returns the latest US print as Helious captures it, with the actual, the consensus forecast, the previous and the surprise in standard deviations. Over the 7 days to 10 November 2026 the median time from publication to the API was 6 seconds. Starter ($14.99 a month) and above serve it live; Pro and Ultimate also push it over the live WebSocket.

Is there a free real-time economic data API?

The first calls are free with no key, an hour behind. A free account key gets 100 credits a month and one live call for 5 credits with fresh=1. Live prints on every call start on Starter at $14.99 a month.

Which US economic series does it cover?

CPI and core CPI, PCE, PPI, nonfarm payrolls and the unemployment rate, jobless claims, GDP and GDPNow, retail sales, the ISM and S&P Global PMIs and the rest of the tracked US series. GET /v1/series lists every slug.

How far back does the history go?

The official table reads the newest 36 observations on every plan, and every observation inside the plan's window beyond them: 12 months on Starter, 24 on Pro and 10 years on Ultimate. The latest level's percentile reads its last 520 official observations on every plan.

Can an AI assistant read it?

Yes. The MCP server at https://api.helious.io/mcp serves the same answer as the get_series tool, and list_series names every slug.