Skip to main content

Series values

Value series (economic indicators, rates, yields and spreads, and physical supply-and-demand statistics) are served as observations of periods. Which series exist is on economic and market series and rates, credit, and volatility; market index levels are bars (price history).

Routes​

taskroute
a series' block and latest valueGET /v1/series/{key}
its observations, newest limit periods (default 24)GET /v1/series/{key}/observations (start, end, known_at)
values that are not observations (projections, forecasts)GET /v1/series/{key}/projections
every served seriesGET /v1/series (series lists)
{"series": {"key": "series:us.cpi.all_items.sa",
            "name": "CPI",
            "shape": "values", "instrument_type": "economic", "asset_class": "not_applicable", "asset_subclass": null,
            "category": "Inflation", "frequency": "monthly", "period_kind": "month", "seasonal_adjustment": "sa",
            "value_kind": "observed", "settlement": null,
            "precision": null,
            "as_published": {"unit": "Index 1982-1984=100", "seasonal_adjustment": "Seasonally Adjusted",
                             "frequency": "Monthly"},
            "unit": {"kind": "index", "multiplier": 1.0, "currency": null, "measure": null, "per": null},
            "field_states": {"settlement": {"state": "unavailable", "reason": "not_applicable", "retry": "never"}}},
 "point_in_time": {"known_at": null, "supported": true, "...": "..."},
 "freshness": {"refreshed_at": "2026-09-27T00:00:00.000000Z", "stale": false, "field_states": null},
 "observations": [
  {"period": {"kind": "month", "label": "2026-08", "start": "2026-08-01", "end": "2026-08-31"},
   "value": 334.131, "value_kind": "observed", "status": null,
   "evidence": "recorded", "known_from": "2026-09-11T13:00:00.000000Z",
   "field_states": {"status": {"state": "unavailable", "reason": "status_not_stated", "retry": "never"}}}],
 "coverage": {"from": {"kind": "month", "label": "2026-06"}, "through": {"kind": "month", "label": "2026-08"},
              "complete": true, "complete_reason": null, "missing": []},
 "field_states": {}}

Freshness fields are defined on freshness.

The series block​

The series block appears in series, in every GET /v1/series row, and in every macro snapshot member. Every field is described in the API reference. To use them:

  • shape: values (observations: /observations) or bars (daily market bars: /history, /technicals).
  • period_kind is what one observation's period is, which can differ from frequency: the Fed's balance sheet is published weekly as a level on one day (calendar_day); initial jobless claims count a whole week.
  • settlement is bar_status for a bar series; for a value series it is null, and finality is each observation's status.

value_kind​

value_kindmeaning
observeda measured value of a completed period
deriveda stated arithmetic over other series
model_outputa stated model's output, for example potential GDP
estimate, forecast, projectionas stated for the value
unknownnot classified (not_applicable)

Where each value states its own kind, field_states.value_kind is value_kind_per_observation, and each observation's value_kind takes precedence.

as_published​

as_published holds the publication's own words, verbatim: unit, seasonal_adjustment, and frequency. They qualify the number (Seasonally Adjusted Annual Rate: the value is an annual rate). Where the serving publication states none, it holds another publication's words for the same measure. On a known_at answer serving a source_vintage value, the words are today's (current_publication_words).

unit​

unit is the value's machine-readable kind and scale, the same at every known_at. No conversion is served.

fieldmeaning
kindpercent (3.75 is 3.75%); percentage_points (a difference of two percents: 0.42 pp = 42 basis points); index; index_points; currency; count; quantity
multiplierone unit of the value is worth multiplier × the base unit: 1000.0 thousands, 1000000000.0 billions
currencyan ISO 4217 code, exactly when kind is currency
measurethe physical unit, exactly when kind is quantity
pera rate's denominator

A base period, a real-dollar reference year, or an annual-rate basis is not in unit; read as_published.

Observations​

Every field is described in the API reference. To use them:

  • status is the value's stated status, for example preliminary. Null with status_not_stated when none is stated: null never means final.
  • value_kind is the value's own kind where one is stated, else the series'.
  • evidence is recorded (as held at that instant) or source_vintage (what was published then; only under known_at). A current value is always recorded.
  • known_from is the instant the value is held from in the answer's knowledge time.

A week is labeled by its last day, its end; the start and end parameters compare with a period's start (pagination).

Served periods​

/observations serves the newest limit periods whose period has ended on or before today, or on or before known_at's date. A period with no value counts toward limit and is listed in coverage.missing. start and end bound the window, and coverage.continue_end pages back.

latest (GET /v1/series/{key}, the macro snapshot, market-view members) is the newest period with a value whose period has ended on or before today.

  • A period still in progress is never latest.
  • A projection or forecast (value_kind) is never latest or an observation, even for an ended period; /projections serves it.
  • A newer period stated to have no value is listed in coverage.missing.

Coverage​

  • complete is true only for a month, quarter, or year series with no hole between from and through; a day or week series is null with not_assessed.
  • missing lists each period with no value that can be named, as {period, reason}. not_held there means no value is held; one may still have been published. A period after through is never listed.
  • continue_end is the end to send, with the same limit, for the next older window; null when no older period is held.

Changes​

Changes appear in macro snapshot members and the VIX term structure's change_5d.

{"basis": "observation_5_back",
 "from_period": {"kind": "calendar_day", "label": "2026-09-18", "start": "2026-09-18", "end": "2026-09-18"},
 "from_value": 4.21,
 "to_period": {"kind": "calendar_day", "label": "2026-09-25", "start": "2026-09-25", "end": "2026-09-25"},
 "to_value": 4.13,
 "absolute": -0.08,
 "absolute_unit": {"kind": "percentage_points", "multiplier": 1.0, "currency": null, "measure": null, "per": null},
 "change_percent": null,
 "field_states": {"change_percent": {"state": "unavailable", "reason": "not_applicable", "retry": "never"}}}

absolute is in absolute_unit (percentage_points for a percent value, index_points for an index level, otherwise the value's unit). change_percent is null with not_applicable where a percent has no meaning, including over a base at or below zero (changes and percents).

basisthe change is taken against
previous_periodthe adjacent earlier period (a month, quarter, year, or week series)
previous_observationthe previous observation held, which may lie across a gap (from_period says which). A day series' change is always this, and steps over a holiday as over a weekend
year_agoexactly the period a year earlier
year_ago_nearestthe observation held nearest a year earlier (from_period says which)
observation_5_back5 observations held earlier: the VIX term structure's change_5d

Point in time​

/observations?known_at=<instant> answers with the newest periods known at that instant. Each period's value is the one in force then: the publisher's vintage, for a time before the period was recorded, and the recorded value from then on. An answer can mix the two; each observation's evidence says which. The shared fields and the rule for an instant before since are on point in time.

A series' point_in_time also carries:

fieldmeaning
sincethe first published vintage held when historical_vintages.status is complete, otherwise recorded_since
recorded_sincewhen the dated record of the series begins
evidenceunder known_at: recorded, source_vintage, or mixed over the observations served
historical_vintagesstatus complete (the published vintages are held) or unsupported (not served; reason says why, and the series answers from recorded_since); horizon, the newest vintage date held
segmentsfor a concept served from different publications over time: each interval, oldest first, with its own since, recorded_since, and historical_vintages. Null when one publication has always served it

Reading a vintage​

To read the vintage dated d, send a known_at from d + 1 00:00 America/Chicago; a known_at on day d reads the earlier value.