Options · Reference and discovery
Options sessions
Trading sessions of an underlying and the history recorded for them.
GET
/v1/options/sessionsoptionsSessionsThe session calendar of an underlying: the market state now, the overnight, regular and curb sessions of the current trading date with their state and times, the last completed session, the newest recorded sessions with the state of their quote and trade history (how many trades, how many gaps), and the exchange holidays and early closes. Use it to find which dates the history routes can serve before asking for them. date selects the trading date the listing starts from; session=gth lists overnight sessions and requires the overnight entitlement.
Example request
curl -sS --get "https://api.ordermap.si/v1/options/sessions" \
-H "Authorization: Bearer $ORDERMAP_API_KEY" \
--data-urlencode underlying_symbol=SPXWconst params = new URLSearchParams({
underlying_symbol: "SPXW",
});
const res = await fetch(`https://api.ordermap.si/v1/options/sessions?${params}`, {
headers: { Authorization: `Bearer ${process.env.ORDERMAP_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data, meta } = await res.json();
console.log(data, meta.coverage);Set ORDERMAP_API_KEY to your key. Replace the dates with a recent trading date.
Parameters
4 parameters, none required.
| Parameter | Type and limits | Description |
|---|---|---|
underlying_queryoptional | stringdefault SPXat most 8 characterspattern ^[A-Za-z][A-Za-z0-9.]{0,7}$ | Underlying: an option root (SPXW, QQQ ...) or an index family (SPX covers SPX and SPXW). |
datequeryoptional | stringdate | Trading date the listing starts from, YYYY-MM-DD; the default is the current or latest session. |
sessionqueryoptional | stringrthgthdefault rth | Session whose history to list: rth (regular) or gth (overnight, which requires the overnight entitlement). |
countqueryoptional | integerdefault 10min 1max 20 | Number of recorded sessions to list, newest first. |
Response
| Status | Meaning | Body |
|---|---|---|
200 | Successful response. | Schema below |
400 | Invalid, unknown or repeated parameters, or an invalid cursor. | Error object |
401 | Missing or invalid API key. | Error object |
403 | The plan, dataset release or account state does not allow this request. | Error object |
422 | The request is valid but no data exists for it. | Error object |
429 | Rate limit, burst limit or cooldown; wait Retry-After seconds.Retry-After | Error object |
500 | Internal error. | Error object |
503 | Data temporarily unavailable; retry after Retry-After seconds.Retry-After | Error object |
504 | The request timed out. | Error object |
Authenticated responses carry the X-RateLimit-* headers (see rate limits); 429 and 503 add Retry-After.
200 response body
dataobjectrequiredSession calendar of an underlying.24 fields insidehistoryarray<object>requiredRecorded sessions, newest first.9 fields insideavailable_on_requestbooleanrequiredThe session can be served on demand even though it is not recorded yet.end_timestampinteger | nullunix-msrequiredEnd of the session. Unix epoch milliseconds (UTC).gapsintegerrequiredGaps in the recorded trades.quote_history_statestringrequiredState of the recorded quote history.readyrecordingqueuedrunningfailedunavailablenot_requestedsessionstringrequiredSession.start_timestampinteger | nullunix-msrequiredStart of the session. Unix epoch milliseconds (UTC).trade_countintegerrequiredTrades recorded.trade_history_statestringrequiredState of the recorded trade history.livecompletepartialqueuedrunningunavailablenot_requestedtrading_datestringrequiredTrading date, YYYY-MM-DD.
holidaysarray<object>requiredExchange holidays and early closes.2 fields insidedatestringrequiredDate, YYYY-MM-DD.typestringrequiredKind of close.full_closeearly_close
last_completedobjectrequiredThe last completed session.2 fields insidesessionstringrequiredSession.trading_datestringrequiredTrading date of the last completed session.
market_statestringrequiredState of the options market now.openpost_cash_closecurb_opength_openclosedsessionsarray<object>requiredSessions of the current trading date.4 fields insideend_timestampinteger | nullunix-msrequiredEnd of the session. Unix epoch milliseconds (UTC).sessionstringrequiredSession.gthrthcurbstart_timestampinteger | nullunix-msrequiredStart of the session. Unix epoch milliseconds (UTC).statestringrequiredlive: trading now; upcoming; completed; not_applicable: the underlying has no such session.liveupcomingcompletednot_applicable
trading_datestringdaterequiredCurrent trading date.underlying_symbolstringrequiredUnderlying the calendar belongs to.
metaobjectrequiredMeta object
Example response
{
"data": {
"underlying_symbol": "SPX",
"market_state": "open",
"trading_date": "2026-10-16",
"sessions": [
{
"session": "gth",
"state": "completed",
"start_timestamp": 1792124100000,
"end_timestamp": 1792146300000
},
{
"session": "rth",
"state": "live",
"start_timestamp": 1792157400000,
"end_timestamp": 1792181700000
},
{
"session": "curb",
"state": "upcoming",
"start_timestamp": 1792181700000,
"end_timestamp": 1792184400000
}
],
"last_completed": {
"trading_date": "2026-10-15",
"session": "rth"
},
"history": [
{
"trading_date": "2026-10-15",
"session": "rth",
"start_timestamp": 1792071000000,
"end_timestamp": 1792095300000,
"available_on_request": true,
"quote_history_state": "ready",
"trade_history_state": "complete",
"trade_count": 412873,
"gaps": 0
}
],
"holidays": [
{
"date": "2026-11-26",
"type": "full_close"
},
{
"date": "2026-11-27",
"type": "early_close"
}
]
},
"meta": {
"as_of": 1760659200123,
"coverage": {
"complete": true
},
"delay_ms": 0,
"delayed": false,
"request_id": "0199f0c2-5a1e-7c3b-9d4e-2b6f8a1c3d5e",
"source": "opra"
}
}Values are illustrative. Missing values are null, never 0.