Economic observations
Revision-aware series observations. as_of selects the latest revision knowable at the cutoff for each series/date. All maturities of a curve are queried as a series set. observation_date is the day of a daily or weekly value and the first day of the month, quarter or year a monthly, quarterly or annual value describes, which period_start and period_end bound. Rates, yields and spreads are in percent (basis-point spreads divided by 100); published_at is the source's release instant where it states one (CFTC swap notionals) and null otherwise. Daily series are refreshed each weekday, World Bank, BIS property and sovereign risk series about monthly. Default order: observation_date ascending, id ascending. Series selection is required. 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/observations- Required capability
- economic.read
- Data timing
- As released
- Credits
- 5 credits per series.
Parameters
series_idsstringrequired · query- Series IDs from economic/series.
fromstringoptional · query- Inclusive lower bound on observation_date.
tostringoptional · query- Inclusive upper bound on observation_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 observation_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- Series ID.
observation_datestring- observation date
period_startstring · null- period start
period_endstring · null- period end
valueobject- currency_code is required when unit=currency and null otherwise. Null value means unavailable, not zero.
published_atstring · null- published at
statusstring- Observation status. reported: the value as the source published it, whose revision state is not established; revised: the value replaced one published earlier for the same date.
preliminaryrevisedfinalmissingreported
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