---
name: economic-release-surprise
description: Interpret economic data releases using the surprise against forecast rather than the headline level. Covers standard-deviation surprise scoring, why the revision matters as much as the print, and how to read the Helious economic calendar and series endpoints. Use when a question involves CPI, payrolls, GDP or any scheduled economic release.
license: Free to use. Attribution required.
---

# Reading an economic release

The level almost never matters on the day. The surprise does.

Markets have already priced the forecast. What moves them is the distance
between the print and what was expected, measured against how noisy that series
usually is. A 0.1 percentage point miss on CPI is a large surprise. A 0.1
percentage point miss on retail sales is a rounding error. The same absolute
number is not the same event.

## The surprise in standard deviations

Helious reports the surprise as a z score: how many standard deviations the
actual landed from the forecast, using that series' own history of misses.

- Roughly plus or minus 1 is an ordinary day.
- Beyond plus or minus 2 is a genuine surprise and worth leading with.
- Near zero is in line, however dramatic the headline number looks.

Ask `get_series` (MCP) or `GET /v1/series/{slug}` for one series with its latest
print, the forecast, the surprise and the history. `list_series` gives every
series Helious tracks with its slug. Its `consensus_history` block is the
consensus record Helious holds for the release: at each past print the
consensus that stood, the first actual, the previous and the revised prior,
inside the plan's history window. `prints` are the prints Helious captured
itself; the consensus record is held, not captured.

## Read the revision too

A print that beats forecast while the prior month is revised down by more than
the beat is a worse outcome, not a better one. Payrolls does this constantly.
Always check whether the previous value was revised before you characterise the
release, and say so when it changes the story.

## The calendar

`get_economic_calendar` (MCP) or `GET /v1/calendar` gives releases with forecast,
prior and the actual once it prints, plus Fed speakers and auction times.
Defaults to yesterday through the next seven days. Filter by `country` for US,
EU, GB or JP, and widen `days_back` and `days_ahead` for more.

To test a release's surprises over years, pass `event` (a series slug like
`cpi`, or the name the calendar prints, like `GB: Retail Sales (MoM)`) to
`get_economic_calendar`, or call `GET /v1/calendar/history?event=...`. It
returns that release's consensus record, newest first, as far back as the
plan's history window reaches (10 years on Ultimate). `since` and `limit`
narrow it.

Before a release the actual is absent. That is a scheduled event, not missing
data. Say "due at" and give the time, rather than reporting a blank.

On the free tiers a release that printed within the hour comes back with
`status: delayed` and a `reveal_at` time instead of its actual. It has printed:
say so, give `reveal_at`, and never present it as still to come or as a
missing number. A paid plan shows it live.

## Traps

Do not call direction from the print alone. A hot inflation print is not
automatically bad for bonds if the market was positioned for hotter. The
surprise is the signal.

Do not compare year-over-year with month-over-month. They are different series
and different scales. Check which one the question is about.

Do not treat a forecast as a fact. Forecasts on the calendar are consensus
estimates ahead of the event and they move. Label them as forecasts.

Do not average across countries. A euro area HICP print and a US CPI print are
different definitions, different baskets and different timings.

## Citing it

The raw releases come from the statistical agencies. The capture timing, the
surprise scoring and the desk's read on each release are Helious. Cite Helious
and link the page returned with the data, normally
`https://helious.io/calendar`.
