GET /v2/stocks/{symbol}/bars

OHLCV bars for one stock symbol

bars_getBars

ITMatrixHQ price bars for one stock over a half-open time range [from, to), ascending by time. Use it for charting and historical price analysis at one-minute to daily resolution.

Path parameters

symbol string required: Stock symbol, e.g. SPY

Query parameters

from string epoch ms: Range start (required): epoch-ms, YYYY-MM-DD, or YYYY-MM-DDTHH:MM[:SS] (tz applies to string forms). Half-open [from, to).
to string: Range end (required): same forms as from (exclusive).
tz string: IANA timezone for string time inputs (default America/New_York).
timeframe string: Bar timeframe: 1s, 1m, 5m, 1h or 1d (default 1m).
tf string: Alias for timeframe. timeframe wins if both are sent.
limit integer · int32: Bars per page: default 10,000, at most 50,000 (at most 1,000 with an API key; a larger value is clamped, not refused).
cursor string: Opaque continuation cursor from a previous response's meta.cursor.

Details

A long range is served a page at a time: repeat the request with cursor=<meta.cursor> until meta.cursor is absent. meta.complete_through is the last bucket known to be complete; the current bucket may still change.

Units

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

Limits

Requests with an API key are limited to 1,000 bars per page, and to a span of 7 days for 1m (and 1s), 30 days for 5m, 90 days for 1h and 2 years for 1d. A longer span or larger limit is clamped, never refused: from moves forward and meta.caps.applied lists range_clamped or limit_clamped. At most 2 requests with the same API key may be in flight on this route at once; another gets 429 rate_limited with Retry-After: 1.

Empty results

A real ticker with no bars in the range returns 200 with an empty data list. A string that is not a ticker at all is 404 not_found.

Example

http

GET /v2/stocks/SPY/bars?timeframe=1d&from=2026-09-21&to=2026-09-26

json

{
  "data": [
    {
      "symbol": "SPY",
      "timeframe": "1d",
      "ts_ms": 1790035200000,
      "open": 774.03,
      "high": 775.14,
      "low": 772.57,
      "close": 773.38,
      "volume": 34802336,
      "trade_count": 470399
    },
    {
      "symbol": "SPY",
      "timeframe": "1d",
      "ts_ms": 1790121600000,
      "open": 772.79,
      "high": 773.05,
      "low": 766.5,
      "close": 767.81,
      "volume": 54931688,
      "trade_count": 614754
    }
  ],
  "meta": {
    "caps": { "tier": "pro", "applied": [] },
    "complete_through": 1790308800000,
    "row_count": 5
  }
}

Response

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

200application/jsonapplication/x-protobuf

Bars in data (epoch-ms bucket starts); meta.caps.applied lists clamps, meta.cursor continues, meta.complete_through is the last bucket. Under Accept: application/x-protobuf the same result is served as the public protobuf body (/v2/rest-protocol.proto); JSON stays the default for every other Accept.

object

A successful response: the payload consumers parse plus response metadata. data shapes are the platform types — never reshaped by the envelope.

data array<object> required

close number · double required

high number · double required

low number · double required

open number · double required

symbol string required

timeframe string required

The aggregate timeframes v2 works with.

One of 1s1m5m1h1d

trade_count integer · int64 nullable

ts_ms integer · int64 required epoch ms

volume integer · int64 required

vwap number · double nullable

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.

Send Accept: application/x-protobuf for a protobuf body instead of JSON — see Protobuf. Errors stay JSON.

Errors

Every error is the JSON error envelope; branch on error.code.

Status	Meaning
400	`invalid_params` — bad epoch-ms/timeframe/source/cursor, or `source=mid` (not served yet)
401	`unauthenticated` / `token_expired`
403	`not_entitled_tier` / `attestation_required`
404	`not_found` — the symbol is not a known ticker (distinct from a real-but-quiet ticker, which is `200` with an empty `data`)
502	`internal` — the selected source failed upstream
503	`internal` — the selected source is not configured here

Request

curl -sS -G "https://api.itmatrixhq.com/v2/stocks/SPY/bars" \
  -H "Authorization: Bearer $ITM_API_KEY" \
  -d "from=2026-09-25" \
  -d "to=2026-09-26" \
  -d "timeframe=5m"

import os
import httpx

response = httpx.get(
    "https://api.itmatrixhq.com/v2/stocks/SPY/bars",
    params={"from": "2026-09-25", "to": "2026-09-26", "timeframe": "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.get_bars("SPY", from_="2026-09-25", to="2026-09-26", timeframe="5m")
    print(result.status, result.data)

const url = new URL("https://api.itmatrixhq.com/v2/stocks/SPY/bars");
url.search = new URLSearchParams({ from: "2026-09-25", to: "2026-09-26", timeframe: "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.getBars("SPY", { from: "2026-09-25", to: "2026-09-26", timeframe: "5m" });
console.log(result.status, result.data);