When did that number actually become public?

/macro-indicator/{country} tells you what a period's value is. It cannot tell you when anyone found out. That job belongs to a different endpoint with a completely different shape.

The calendar endpoint

GET /economic-events takes from and to as YYYY-MM-DD, country as an ISO 3166-1 alpha-2 code (US, DE, GB — note this is two letters, where /macro-indicator/{country} wanted three), comparison as one of mom, qoq or yoy, plus offset (0 to 1000) and limit (0 to 1000, default 50).

The default limit of 50 matters more than it looks. A single US week produces well over a hundred events. Ask for a month without raising limit and you get a silently truncated slice of it.

Unlike the rates and credit endpoints in this course, the response is a bare array with no meta or links wrapper — so there is no total to tell you how much you did not receive. You page by walking offset until you get a short page.

The fields, and what each one means

Each event carries type, comparison, period, country, date, actual, previous, estimate, change and change_percentage. The date is a full timestamp in YYYY-MM-DD HH:MM:SS — this is the release moment, which is the whole point of the endpoint. It is in UTC, and the series proves it without a word of documentation: the monthly US inflation print is stamped 13:30:00 on 13 January and 13 February 2026, then 12:30:00 from 11 March onwards. The release did not move — it is 8:30 in the morning in New York every time — and the one-hour step is the American daylight-saving change seen from UTC. A release timestamp with no zone attached is not yet a market timestamp.

A real row, the June 2026 US inflation print:

Read the three value fields as three different questions. previous is history. estimate is what the consensus expected. actual is what happened. The gap between estimate and actual — here 0.3 percentage points below expectations — is the only part that was genuinely news at 12:30:00 on 14 July; the other two numbers were already known.

Three things that will bite you

estimate is frequently null. Consensus forecasts exist only for events somebody bothers to forecast. In the US week of 13–17 July 2026 estimate is null on every Fed speech, on every bill auction and on most of the EIA inventory lines, while the EIA crude and gasoline stock changes carry one. Any code that computes a surprise must handle the null rather than treating it as zero.

The same release appears under more than one type. In that week, 2026-07-15 14:30:00 carries both EIA Crude Oil Imports Change and Crude Oil Imports, with identical values of −0.399 against a previous of 1.096. Re-counted on 28 September 2026, fourteen timestamps in the week carry more than one row, and most of them are different releases due at the same minute, so the timestamp alone is not a key either. Deduplicate on (date, actual, previous) rather than trusting type to be unique.

Null is not zero. The February 2026 US inflation row has actual 2.4 and previous 2.4 — and change comes back as null, not 0. A pipeline that coalesces null to zero cannot distinguish "unchanged" from "not computed".

Where the calendar and the curve meet

The calendar is not only macro. The same US week contains 17-Week Bill Auction at 2026-07-15 15:30:00 with an actual of 3.745 against a previous of 3.79. That is a primary-market clearing rate for exactly the instrument the next unit's /ust/bill-rates endpoint reports on the secondary market. Two endpoints, two views, one bill.

Try it now

1. Here is /economic-events?country=US&from=2026-07-13&to=2026-07-17 twice: first without limit, then with limit=500. Rows arrive newest first. Compare the last timestamp of each and say which days of the week the default 50 left out. Measured on 28 September 2026, the second call held 115 rows, so the default returned fewer than half of them.

2. Rows that share a timestamp come back in no fixed order, so they are printed here rather than rendered. Nine rows are stamped 2026-07-14 12:30:00, the June CPI release. One is the year-on-year headline row shown earlier in this lesson; these are the other eight, as the week's call returned them on 28 September 2026:

Apply the (date, actual, previous) rule and say whether any two rows are one release under two labels. Then count the rows that share a type, the headline row included, and name the column that tells them apart. Decide your deduplication key before these rows reach a chart. 3. In the same table, take the rows where estimate is not null and compute actual − estimate for each, with its unit. One of them has no actual at all; say what your code does with it. That column, not the actual column, is what the release told the market it did not already know.