Economic calendar
Scheduled and historical economic releases with their actual, forecast and previous values. scheduled_at is the scheduled instant in UTC, null for an entry with no time of day; release_date is its UTC date. The connected source does not report the instant a figure was actually released (released_at), a revised previous value, an importance rating or measurement units, so those stay null or unknown; read the release name for the unit. Public holidays the source calendar lists are not releases and are left out. History comes from the source calendar, which begins in 2020, and is backfilled from the present backwards, so it can start later than 2020 while that runs; GET /v1/datasets/economic.events/coverage reports the current history_from and history_to. Upcoming releases appear about seven days ahead. series_id is null on every event: the calendar source links no release to a series. Default order: release_date ascending, id ascending. Omitting entity selectors returns the entitled universe; explicit unauthorized selectors return 403. Data is delivered from validated canonical batches; a connected dataset with nothing published for the key's markets yet returns 503. Access requires the operation capability on the API key.
/v1/economic/events- Required capability
- economic.read
- Data timing
- As released
- Credits
- 5 credits per request.
Parameters
countriesstringoptional · query- ISO 3166-1 alpha-2 country codes.
series_idsstringoptional · query- Associated economic series. Events are not linked to series yet (series_id is null), so this filter matches none.
fromstringoptional · query- Inclusive lower bound on release_date.
tostringoptional · query- Inclusive upper bound on release_date; must be on or after from, so from equal to to selects one day.
as_ofstringoptional · query- Knowledge cutoff as a UTC date (YYYY-MM-DD): the response reflects what was known by the end of that day. Defaults to now; cannot be in the future. A date from before the dataset's knowledge history returns 422 point-in-time-unavailable naming the earliest one, which GET /v1/datasets lists as earliest_as_of.
known_fromstringoptional · query- First UTC date (YYYY-MM-DD, inclusive) on which a revision became known.
known_tostringoptional · query- Last UTC date (YYYY-MM-DD, inclusive) on which a revision became known; on or after known_from.
orderstringoptional · query- Direction on release_date; ties use ID ascending.
Default:ascdescasc limitintegeroptional · query- Maximum records per page.Default:
100 cursorstringoptional · query- Opaque cursor, expires after one hour; binds filters, order, resolved as_of, account/key and entitlement. Repeat the original query unchanged.
formatstringoptional · query- Response format. csv returns the data rows with a header row, for spreadsheet functions such as IMPORTDATA; nested fields become dotted columns and lists one JSON array cell, the next page cursor is returned in X-Next-Cursor and meta.errors in X-Meta-Errors. A result without rows is the header row alone, listing the documented fields of a row. Default json, or csv when format is omitted and the Accept header ranks text/csv above JSON; a format the Accept header does not admit returns 406 not-acceptable.
jsoncsv
Response fields
Returns data as an array of records. All example values are illustrative.
idstring- Record identifier, stable across revisions.
series_idstring · null- Associated series ID from economic/series. Null when the release is not linked to a published series; the current calendar source links none, so it is null on every event.
namestring- Release name.
country_codestring- country code
release_datestring- UTC date of the scheduled release; a release early in the morning in Asia falls on the previous UTC date.
scheduled_atstring · null- Instant the release is scheduled for, in UTC. Null for an entry the source lists without a time of day (elections, meetings, some auctions).
released_atstring · null- Instant the figure was actually released. The connected source does not report it: always null. status tells whether the actual value has arrived.
reference_periodstring · null- Source reference period.
importancestring- Source-assigned importance. The connected source assigns none: always unknown.
lowmediumhighunknown actualobject- currency_code is required when unit=currency and null otherwise. Null value means unavailable, not zero.
forecastobject- currency_code is required when unit=currency and null otherwise. Null value means unavailable, not zero.
previousobject- currency_code is required when unit=currency and null otherwise. Null value means unavailable, not zero.
revised_previousobject- currency_code is required when unit=currency and null otherwise. Null value means unavailable, not zero.
statusstring- Release status: released once the source reports an actual value, otherwise scheduled, including past entries that carry no figure (speeches, meetings); the connected source reports no postponed or cancelled releases.
scheduledreleasedpostponedcancelled
Response metadata
Responses include meta.timezone. Dataset responses include next_cursor; health and exports have their own metadata. Request tracing uses the X-Request-ID header.
When something goes wrong
An empty data: [] is a successful query with no matching records. Invalid symbols, permissions and malformed parameters produce an RFC 9457 problem with an actionable detail.
Plans
Requires economic.read. Access, recency and history depth come from the plan definitions the API enforces.
| Plan | Access | Recency | History |
|---|---|---|---|
| Free | Not included | — | — |
| Developer | Not included | — | — |
| Pro | Included | As released | 15 years |
| Commercial | Included | As released | Full history |
| Scale | Included | As released | Full history |
History is how far back a plan may request. How far records actually go for a symbol is history_from in dataset coverage. Nothing is real-time. Compare plans