Listing lifecycle

A security's answers change when its listing left the maintained universe, was never maintained, was just added, or was delisted. These states explain a 404 not_maintained, 404 delisted, or 503 temporarily_unavailable, and a history that ends early.

Listing state

fact	where
whether it is still maintained	instrument.maintenance
its lifecycle: listed or delisted	instrument.listing
how far its history reaches	instrument.maintenance.coverage_end

Every security answer states the first two in its instrument block. Leaving the maintained universe is not a delisting.

GET /v1/instruments lists departed and delisted listings only with coverage=all, with current listings first (Find an instrument). GET /v1/instruments/{key} states them under identity.maintenance (state, coverage_end) and identity.listing (state, delisted_at, delisting_reason).

Price-dependent profile figures

For a listing that is no longer updated, a profile's price-dependent figures are null: market cap, EV, the price multiples, dividend yield and rate, the betas, fund NAV, yield, five-year return, days_to_cover, and market_cap_basis. The reason is field_states.*.reason: no_longer_maintained for a departed listing and delisted for a delisted one.

Departed listings

A departed listing has maintenance.state: departed and listing.state: listed. It is no longer updated, and its held data stays readable.

reads	answer
current: quote, technicals, analyst consensus, earnings calendar, research	404 not_maintained; the error object carries maintenance: {state: departed, coverage_end}
batch quote	the member is under errors, with code: not_maintained
history: daily and intraday bars, profile, corporate actions, filings, financials, events, news, digest, thesis	the held data, each answer carrying instrument.maintenance: {state: departed, coverage_end}

On the history reads:

• The bar window ends on coverage_end, the newest session held. Its freshness.stale is null with field_states.stale.reason: no_longer_maintained; read the age from freshness.refreshed_at. A window anchored after coverage_end is its newest window.
• Bars that had not settled when the listing left stay unsettled and will not be confirmed later (field_states.status: unconfirmed).
• The corporate actions' freshness.stale is null with the same reason.
• A profile that was never held before the listing left is 404 not_maintained (with maintenance), not 503 temporarily_unavailable. For a delisted listing it is 404 delisted.

The ticker resolves exactly as for any current listing. A departed listing's datasets are the history datasets it holds (securities.profile only when a profile is held).

Unmaintained and newly added listings

A listing with maintenance.state: not_maintained is registered, but its prices are not maintained. Its quote, history, technicals, and reference-data reads are 404 not_maintained; its filings and content reads answer from the data held.

A maintained listing whose daily history is not yet available, such as a listing just added to the maintained universe, lists its bar datasets. Its daily bars, intraday bars, and technicals answer:

state	answer
history not yet available, or not obtainable at the moment	503 temporarily_unavailable
no daily history is published for it	404 not_published

A listing younger than the history window (an IPO, a spin-off) is served from its first bar, and the window is marked insufficient_history (window_bound: history_depth).

Delisted listings

reads	answer
current: quote, technicals, analyst consensus, earnings calendar, research	404 delisted, with the effective date, the reason, and the evidence
batch quote	the member is under errors, with code: delisted
history: bars, profile, corporate actions, filings, financials, events, news, digest, thesis	served while the ticker names the listing unambiguously

Every history answer's instrument.listing states:

• state: delisted;
• delisted_at: the first session it did not trade, not the filing's legal date;
• delisting_reason: acquired or exchange_delisting.

Its bar window ends on its last listed session. Its corporate actions are served with its bars, never as current: freshness.stale is null with field_states.stale.reason: delisted.

Reused tickers

• A ticker a current listing holds always names that listing, and a former holder's history is never mixed in. The former holder's venue form (XNAS:ACQ, key security:XNAS:ACQ) is then 404 delisted.
• Several delisted listings under one ticker, and no current one, is 409 ambiguous_instrument, naming the venue forms.
• A ticker two current listings hold is 409 ambiguous_instrument, as for any listing.

The full list of codes is on Errors.