Values and data quality

Every response follows these conventions for numbers, units, and scale, and for saying why a field or an answer cannot be plainly served.

Numbers and rounding

instrument.price_precision and a series' precision state the decimal places a value is served to; null means the source's own decimals. It is the same on every route that serves a key (quote, history, technicals).

values	precision
a security's prices	4 decimal places; a 2-decimal traded price is served exactly
FX rates	5 decimal places; 3 for a pair quoted in yen (USDJPY, EURJPY)
market series bars and quotes (index levels, yield indices, futures)	the series' precision where one is set (index levels 2, yields 3); a futures series has none (price_precision null)
crypto pairs	the exchange's own decimals (price_precision null)
economic values	the published decimals, never rounded (precision null)
reference data (profile, analyst, calendar)	4 decimal places, and a fraction below 1 to 4 significant figures (profit_margin 0.2762)
usage percentages	4 decimal places

Technical indicators and crypto asset rows have their own precision, stated on technicals and crypto.

How a number is encoded

kind	encoding	examples
fraction	a decimal fraction; it can be negative or exceed 1. The default for margins, returns, growth rates, ownership and yields (dividend_yield, payout_ratio, held_fraction_institutions, short_fraction_of_float)	dividend_yield: 0.0047 = 0.47%; revenue_growth: 1.059 = +105.9%
percent	already multiplied by 100; the name ends in _percent or _pct	change_percent: -0.589 = a 0.589% fall
percentage points	a difference of two percent levels (a series' unit.kind: percentage_points)	from 4% to 5% is 1.0
multiple	a ratio of two named quantities (pe_ratio, price_to_book, current_ratio, debt_to_equity)	pe_ratio: 39.88 = 39.88 times earnings
amount per share	in instrument.currency, for example dividend_rate	1.08 on a USD listing = USD 1.08 a year
duration	the unit is in the name	days_to_cover: 2.82 = 2.82 trading days
money and quantities	currency, scale, and basis from the answer's own fields (currency, price_scale, *_basis)

A value series states its unit in its series block (series values). An SEC value's unit is on filings and financials.

Changes and percents

A change (change, absolute) is the exact decimal difference of its two operands as served: 59.61 − 58.42 is 1.19, and a sub-cent change is served as it is (0.0042).

Every percent change (change_percent) is a percent, rounded to 4 decimal places. A change in a series that is itself a percent, such as a yield, is in percentage points, and its percent change is null with not_applicable.

Currency and quotation scale

currency is the instrument's money or settlement currency: an ISO 4217 code for a listing (its trading currency), an FX pair (its quote currency) and a futures family; for a crypto pair, the quote asset as the exchange lists it, which can be USDT or another coin (BTC for ETH-BTC). It is null for an index level, a yield or a rate, and for an instrument whose currency is not held. A null currency or price_scale says why in instrument.field_states on every route that serves the block.

price_scale is what one unit of a price is worth in currency: 1 is the major unit, 0.01 the minor unit. A future quoted in US cents has currency USD and price_scale 0.01 (corn at 522 is 5.22 USD a bushel). Where a price is not an amount of the currency (index points, percent of par), price_scale is null. The values are listed on quotes.

price_scale applies to price, change, previous_close, change_reference, the day open, high and low, the book bid and ask, range_52w, a bar's open, high, low and close, and the technical levels. market_cap, turnover, percentages and volumes are never scaled. price_scale is not a decimal-place count (that is price_precision), and the contract's unit of measure (per bushel, per barrel) is not stated.

Field states

Data responses carry field_states: a map from a field (a dotted path for a nested one, for example day.date, book.bid_size) to {state, reason, retry}. A field absent from the map is served without qualification.

state	meaning
withheld	a value exists but is known or suspected to be wrong, so it is not served. The field is null; do not substitute another value
unavailable	there is no value. The field is null
unverified	a value is served, with a limit to account for before you use it (for example provisional: a bar captured mid-session)

The reason not_applicable (state unavailable) says the field does not apply to this kind of instrument, for example a series quote's book or a yield's change_percent.

retry belongs to the reason, so a reason always carries the same retry:

retry	meaning
later	the same request may get a value later
never	asking again does not change it; it changes only if the publisher revises
change_request	this request cannot get a value; the reason's action names the request that can

Reason codes

A reason is a code from one closed list, grouped by what to do:

Use it

reason	state	retry	what to do
split_adjusted	unverified	never	Compare it only with post-split prices
value_kind_per_observation	unverified	never	Read each observation's value_kind
top_members_only	unverified	never	Read the list as partial; size counts every member
amendment_not_combined	unverified	never	Read it beside the report; never add the two
quarterly_ytd_only	unverified	never	Do not read the missing quarters as zero
possibly_incomplete	unverified	later	Use it, and ask again later for the newest records

Use it with care

reason	state	retry	what to do
unconfirmed	unverified	never	Check it before relying on it
provisional	unverified	later	Ask again after the session settles for the final value
truncated	unverified	never	Do not read the ending as complete
no_longer_published	unverified	never	Read it as the last value, not a current one
current_publication_words	unverified	never	Do not read the wording as point-in-time
acceptance_time_uncertain	unverified	never	Use a known_at clear of the acceptance time
acceptance_unknown	unverified	never	Do not read the fact as known at any instant
status_not_stated	unavailable	never	Never read the value as final

Retry later

reason	state	retry	what to do
temporarily_unavailable	unavailable	later	Treat it as unknown, never as zero, and ask again later
not_current	withheld	later	Read the next quote
quote_too_old	withheld	later	Ask again for a current quote
off_session_indicative	withheld	later	Use the next session's quote for daily figures
contract_roll	withheld	later	Compare prices within one contract
document_unavailable	withheld	later	Ask again later, or read the cited articles

Change the request

reason	state	retry	what to do
insufficient_history	unavailable	change_request	Ask for a shorter period, a later end, or from available_from
not_offered	unavailable	change_request	Ask for a period or interval the operation lists
none_in_period	unavailable	change_request	Ask for a wider or different period
none_known_at	unavailable	change_request	Ask with a later known_at
before_point_in_time_history	unavailable	change_request	Ask with a known_at at or after point_in_time.since
instant_not_placed	unavailable	change_request	Ask with period_type=instant
not_in_this_quote	unavailable	change_request	Read it from the bars or the profile
not_registered	unavailable	change_request	Search GET /v1/instruments?q= and use the key it returns
ambiguous_instrument	unavailable	change_request	Use the venue-qualified instrument key
content_withdrawn	withheld	change_request	Read the newest document that is not withdrawn

Not held

reason	state	retry	what to do
not_held	unavailable	never	Treat it as unknown, never as zero
not_published	unavailable	never	Do not fill it from another field, day or period
status_withdrawn	unavailable	never	Do not use an earlier copy as current
succession_undetermined	unavailable	never	Do not join the histories
unreliable	withheld	never	Do not fill it from another day or source
basis_unclear	withheld	never	Do not combine it with the price or other share counts
conflicting_assertions	withheld	never	Compare the listed values
daily_close_undefined	withheld	never	Use the reference rates for a daily fixing
no_longer_maintained	withheld	never	Read its history, which stays available
document_invalid	withheld	never	Use another document or the sources directly

Accounted for, not a gap

reason	state	retry	what to do
confirmed_absent	unavailable	never	Count the session as accounted for, not as a gap
delisted	unavailable	never	Expect no later bars

Does not apply

reason	state	retry	what to do
not_applicable	unavailable	never	Ignore the field
not_assessed	unavailable	never	Do not read the null as complete or current
quoted_in_points	unavailable	never	Do not convert the price to currency

Missing values

Data outside coverage, not collected yet, or not refreshed yet is answered with a typed state:

• A whole answer that cannot be given is an error with a code, such as 404 not_maintained (outside the maintained universe) or 503 temporarily_unavailable (maintained, nothing stored yet).
• A value that cannot be stated is null, and its entry in field_states says why (field states). A null with no entry has no stated reason.

A null is never a zero or a placeholder, and a number is never filled in from a neighboring fact. For whether retrying helps, read the error's retry (error codes).