/v2/symbols/lookup Check whether a ticker exists
reference_lookupSymbol
Whether a typed ticker is a real, addressable symbol, with its name and class. Use it to validate input as the user types; it reports existence and identity only, never entitlement.
Query parameters
qstringThe typed ticker (required). Trimmed and uppercased before lookup.
Details
q is trimmed and uppercased first. Registry symbols answer immediately; other tickers are checked against reference data and the answer, positive or negative, is cached, so per-keystroke calls are cheap. Repeated identical answers carry the same ETag, so a conditional request gets 304.
Limits
No per-operation limit applies to requests with an API key.
Empty results
A ticker that does not exist returns 200 with valid: false. When existence cannot be decided, valid is false and meta.note says why.
Example
GET /v2/symbols/lookup?q=aapl{
"data": {
"valid": true,
"symbol": "AAPL",
"name": "Apple Inc.",
"class": "equity",
"instrument_type": "common_equity",
"instrument_type_source": "provider_reference",
"instrument_type_as_of": null
}
}Response
Prices are dollars, timestamps epoch milliseconds, strikes integer thousandths of a dollar; null means unknown. Units →
200application/json
{valid, symbol, name, class} in data — existence and identity only, never entitlement data. x-itm-symbol-lookup reports whether the answer came from the registry, the lookup cache or a reference-data lookup.
object
A successful response: the payload consumers parse plus response metadata. data shapes are the platform types — never reshaped by the envelope.
data object required
Existence, broad class and conservative instrument classification.
class string nullable Asset class ("equity"|"index"), when known.
instrument_type string required Instrument type, independent of class: common_equity, etf, index, adr_other, or unknown when it cannot be classified.
instrument_type_as_of string nullable Always null for now: no effective classification date is published.
instrument_type_source string nullable Where instrument_type came from (for example provider_reference), or null when it is unknown.
name string nullable Display name, when one is known. null for an invalid symbol, and for a valid one whose name is not resolved yet.
symbol string required The normalized form of what was asked for (trimmed + uppercased).
valid boolean required Whether this is a real, addressable ticker.
meta object required
Response metadata.
caps object nullable
meta.caps — the entitlement caps that shaped this response. applied lists the caps that actually changed it (for example range_clamped).
applied array<string> required Which caps actually shaped this response (e.g. range_clamped). Empty = nothing was clamped.
darkpool boolean nullable Whether this account can use Off-Exchange in the site.
flow boolean nullable Whether the OPRA option-flow capability (flow) is granted to this principal in the app: site Pro plus a CBOE non-professional attestation (never on an itm_ key). Emitted explicitly — true and false — by the account endpoints, so the app reads the grant instead of inferring it from tier and attestation; absent on routes that do not report it.
gexDepth string nullable GEX data depth when the route reports it. Camel-cased to match the browser capability bundle; absent on unrelated routes.
tier string required The tier the request was served under.
cursor string nullable Opaque continuation cursor (pass back as ?cursor=); absent when there is nothing more to read.
plane string nullable Which serving tier answered the read (meta.plane). Informational provenance: treat it as an opaque label, because new values may appear.
Errors
Every error is the JSON error envelope; branch on error.code.
| Status | Meaning |
|---|---|
| 400 |
|
| 401 |
|