GET /v2/options/{contract}/bars

Intraday trade bars for one option contract

bars_getOptionBars

One- or five-minute OHLCV bars of one option contract's trades for one exchange session, ascending by time. Use it to chart a contract's intraday price and volume.

Path parameters

contract string required: Option contract: O: + OSI symbol, e.g. O:SPY260925C00765000

Query parameters

tf string: Bar size: 1m (default) or 5m.
session string ISO date: Exchange session, ISO YYYY-MM-DD (ET). Default: today when the exchange trades today, otherwise the previous trading day, so a weekend or holiday request answers for the last session. The session served is echoed in meta.session.
limit integer · int32: Keep the newest N bars: default 390, at most 2000 (larger values are clamped).

Details

The contract is O: plus its OSI symbol, e.g. O:SPY260925C00765000: root, YYMMDD expiry, C or P, then the strike × 1000 zero-padded to 8 digits. The session served is echoed in meta.session.

Units

ts_ms is the epoch-millisecond start of the bar.
open, high, low, close and vwap are dollars per share.
volume is contracts; vwap and trade_count appear when known.

Freshness

Recent sessions only. A completed session is available after the end-of-day reconciliation. Bars for the current session exist only while ITMatrixHQ is following the contract live.

Limits

At most 2,000 bars per response for every caller: a larger limit is clamped and meta.limit_clamped is true. No other per-operation limit applies.

Empty results

A contract and session with no bars returns 200 with bars: [] and a meta.note; nothing is synthesized. An underlying outside the symbol registry is 404 not_found.

Example

http

GET /v2/options/O:SPY260925C00765000/bars?session=2026-09-24&limit=2

json

{
  "data": {
    "contract": {
      "underlying": "SPY",
      "expiry": "2026-09-25",
      "right": "call",
      "strike": 765000
    },
    "timeframe": "1m",
    "bars": [
      {
        "ts_ms": 1790256600000,
        "open": 3.42,
        "high": 3.55,
        "low": 3.38,
        "close": 3.51,
        "volume": 1184,
        "vwap": 3.47,
        "trade_count": 212
      },
      {
        "ts_ms": 1790256660000,
        "open": 3.51,
        "high": 3.6,
        "low": 3.47,
        "close": 3.58,
        "volume": 906,
        "vwap": 3.54,
        "trade_count": 174
      }
    ]
  },
  "meta": { "session": "2026-09-24", "count": 2 }
}

Response

Prices are dollars, timestamps epoch milliseconds, strikes integer thousandths of a dollar; null means unknown. Units →

200application/json

{contract, timeframe, bars} in data, bars ascending by ts_ms; meta.session, meta.count, meta.note when empty

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

bars array<OptionBarValue> required

close number · double required

high number · double required

low number · double required

open number · double required

trade_count integer · int64 nullable

ts_ms integer · int64 required epoch ms

volume integer · int64 required

vwap number · double nullable

contract object required

A single listed option contract, identified the way the OSI does: root symbol, expiry date, right, strike.

underlying is the OSI root (e.g. SPXW for SPX weeklies), stored unpadded and uppercase.

expiry string · date required ISO date

right string required

Call or put.

One of callput

strike integer · int64 required 1/1000 $

Strike in integer thousandths of a dollar (exact OSI unit)

underlying string required

timeframe string required

The aggregate timeframes v2 works with.

One of 1s1m5m1h1d

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	`invalid_params`
401	`unauthenticated`
403	`not_entitled_tier`
404	`not_found` — underlying is not registered
503	`provider_unavailable`

Request

curl -sS -G "https://api.itmatrixhq.com/v2/options/O%3ASPY261016C00600000/bars" \
  -H "Authorization: Bearer $ITM_API_KEY" \
  -d "tf=5m"

import os
import httpx

response = httpx.get(
    "https://api.itmatrixhq.com/v2/options/O%3ASPY261016C00600000/bars",
    params={"tf": "5m"},
    headers={"Authorization": f"Bearer {os.environ['ITM_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

import os
import itmatrix as itm

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    result = client.market.option_bars("O:SPY261016C00600000", tf="5m")
    print(result.status, result.data)

const url = new URL("https://api.itmatrixhq.com/v2/options/O%3ASPY261016C00600000/bars");
url.search = new URLSearchParams({ tf: "5m" }).toString();

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ITM_API_KEY}` },
});
console.log(response.status, await response.json());

import { ITMClient } from "@itmatrixhq/core";

const client = new ITMClient({ apiKey: process.env.ITM_API_KEY });
const result = await client.market.optionBars("O:SPY261016C00600000", { tf: "5m" });
console.log(result.status, result.data);