{ "openapi": "3.1.0", "info": { "title": "Market History API", "version": "2026.10.15.1", "summary": "Historical market bars (OHLCV) over HTTP.", "description": "Read-only JSON/binary over `GET`.\n\n**Billed** bar queries go through `/query/v1/bars/...` and need an `Authorization: Bearer ` header (or a browser session); each page spends bars in blocks of 100, reported in `X-Bars-Charged`.\n\n**Free sample:** `/api/v1/bars/{source}/{ticker}/1h` needs no key: hourly bars of one ticker over the last five years.\n\n**L3 order book:** `/query/v1/mbo/stocks-venue-l3/{ticker}`, every published session, billed at 10 events per bar; free sample at `/api/v1/mbo/stocks-venue-l3/{ticker}`.\n\n**L2 top of book:** `/query/v1/l2/stocks-venue-l2/{ticker}`, 1s best bid and offer for the same sessions, billed like 1s bars; free sample at `/api/v1/l2/stocks-venue-l2/{ticker}`.\n\n**Funding rates:** `/query/v1/funding?symbol={ticker}`, every funding event of a crypto perpetual, billed like bars.\n\n**Perpetual prices:** `/query/v1/prices?symbol={ticker}&kind=mark` (or `index`, `premium`), 1m OHLC, billed like bars.\n\n**Open interest:** `/query/v1/open-interest?symbol={ticker}`, 5m open interest and long/short ratios, billed like bars.\n\n**Corporate actions:** `/query/v1/corporate-actions?symbol={ticker}`, equity splits, dividends, symbol changes and mergers, free with any key; `adjust=splits` or `adjust=all` on bars applies them.\n\n**Unmetered** catalogue endpoints live under `/api/` and need no key.\n\nPick the encoding with `format=`; on `/api/` that is the only way (the `Accept` header is ignored there).\n\nDefault `limit` is 1000, the maximum is 100000. Page through larger ranges with the `cursor` from `X-Next-Cursor` (also offered as `Link: <...>; rel=\"next\"`).\n\nGenerated from the service source by `tools/gen_openapi.py`; do not edit by hand.", "contact": { "url": "https://getmarkethistory.com", "email": "support@getmarkethistory.com" } }, "servers": [ { "url": "https://getmarkethistory.com" } ], "tags": [ { "name": "bars", "description": "Billed bar queries." }, { "name": "l3", "description": "Billed L3 order-book events." }, { "name": "l2", "description": "Billed 1s top of book." }, { "name": "depth", "description": "Billed venue depth (market by price)." }, { "name": "funding", "description": "Billed perpetual funding rates, mark/index/premium prices, open interest." }, { "name": "actions", "description": "Equity corporate actions, free with any key." }, { "name": "sample", "description": "The free 1h sample, no key needed." }, { "name": "catalogue", "description": "Unmetered metadata, no key needed." } ], "paths": { "/api/v1/bars/{source}/{ticker}/{timeframe}": { "get": { "operationId": "getSampleBars", "summary": "Free 1h sample for one symbol", "description": "Free, no key: hourly bars of one ticker over the last five years. Other timeframes or several tickers answer 400; use the billed `/query/` path with a key.", "tags": [ "sample" ], "security": [], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Dataset id, e.g. `stocks`; `/api/v1/sources` lists them all.", "schema": { "type": "string" }, "example": "stocks" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "timeframe", "in": "path", "required": true, "description": "Must be `1h`.", "schema": { "type": "string", "enum": [ "1h" ] }, "example": "1h" }, { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/columns" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/end" }, { "$ref": "#/components/parameters/between" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of 1h bars, oldest first. With no `start`/`end`/`cursor`: the newest bars, at most `X-Preview-Limit`.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Preview-Limit": { "$ref": "#/components/headers/X-Preview-Limit" }, "X-Preview-From": { "$ref": "#/components/headers/X-Preview-From" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.manifoldbt.mbt1": { "schema": { "type": "string", "format": "binary", "description": "`format=mbt1`; timestamps unix_ns. Accept: application/vnd.manifoldbt.mbt1, application/x-mbt1" } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/bars": { "get": { "operationId": "querySampleBars", "summary": "Free 1h sample by query", "description": "Free, no key: hourly bars of one ticker over the last five years. Other timeframes or several tickers answer 400; use the billed `/query/` path with a key.", "tags": [ "sample" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/columns" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/end" }, { "$ref": "#/components/parameters/between" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/ticker" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/source" } ], "responses": { "200": { "description": "A page of 1h bars, oldest first. With no `start`/`end`/`cursor`: the newest bars, at most `X-Preview-Limit`.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Preview-Limit": { "$ref": "#/components/headers/X-Preview-Limit" }, "X-Preview-From": { "$ref": "#/components/headers/X-Preview-From" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.manifoldbt.mbt1": { "schema": { "type": "string", "format": "binary", "description": "`format=mbt1`; timestamps unix_ns. Accept: application/vnd.manifoldbt.mbt1, application/x-mbt1" } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/bars/{source}/{ticker}/{timeframe}": { "get": { "operationId": "getBars", "summary": "Bars for one symbol (billed)", "tags": [ "bars" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Dataset id, e.g. `stocks`; `/api/v1/sources` lists them all.", "schema": { "type": "string" }, "example": "stocks" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "timeframe", "in": "path", "required": true, "description": "Bar timeframe, e.g. `1s`, `1m`, `1h`, `1d`.", "schema": { "type": "string" }, "example": "1h" }, { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/columns" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/end" }, { "$ref": "#/components/parameters/between" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/adjust" } ], "responses": { "200": { "description": "A page of bars, oldest first.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.manifoldbt.mbt1": { "schema": { "type": "string", "format": "binary", "description": "`format=mbt1`; timestamps unix_ns. Accept: application/vnd.manifoldbt.mbt1, application/x-mbt1" } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/bars": { "get": { "operationId": "queryBars", "summary": "Bars by query string (billed)", "tags": [ "bars" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/columns" }, { "$ref": "#/components/parameters/start" }, { "$ref": "#/components/parameters/end" }, { "$ref": "#/components/parameters/between" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/ticker" }, { "$ref": "#/components/parameters/timeframe" }, { "$ref": "#/components/parameters/source" }, { "$ref": "#/components/parameters/adjust" } ], "responses": { "200": { "description": "A page of bars, oldest first.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.manifoldbt.mbt1": { "schema": { "type": "string", "format": "binary", "description": "`format=mbt1`; timestamps unix_ns. Accept: application/vnd.manifoldbt.mbt1, application/x-mbt1" } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/mbo/{source}/{ticker}": { "get": { "operationId": "getSampleMbo", "summary": "Free L3 sample for one symbol", "description": "Free, no key: the first 1,000 events after 09:30 ET of the newest session held; no paging (`date`, `start`, `end`, `cursor` answer 400).", "tags": [ "sample" ], "security": [], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The L3 dataset id; `/api/v1/sources` lists them under `l3`.", "schema": { "type": "string" }, "example": "stocks-venue-l3" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "limit", "in": "query", "description": "Events per page (default 10,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of book events.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Preview-Limit": { "$ref": "#/components/headers/X-Preview-Limit" }, "X-Preview-From": { "$ref": "#/components/headers/X-Preview-From" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/mbo/{source}/{ticker}": { "get": { "operationId": "getMbo", "summary": "L3 order-book events for one symbol (billed)", "description": "L3 (market by order) events of one ticker, every published session, oldest day first, sequence order within a day. Billed at 10 events per bar, in blocks of 1,000 events.", "tags": [ "l3" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The L3 dataset id; `/api/v1/sources` lists them under `l3`.", "schema": { "type": "string" }, "example": "stocks-venue-l3" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "date", "in": "query", "description": "One trading session, `YYYY-MM-DD`; a session not published is a 404.", "schema": { "type": "string", "format": "date" } }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Events per page (default 10,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "description": "`X-Next-Cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of book events.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/l2/{source}/{ticker}": { "get": { "operationId": "getSampleL2", "summary": "Free L2 sample for one symbol", "description": "Free, no key: the newest 100 rows (`X-Preview-Limit`). It does not page: `date`, `start`, `end` and `cursor` are a 400.", "tags": [ "sample" ], "security": [], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The L2 dataset id; `/api/v1/sources` lists them under `l2`.", "schema": { "type": "string" }, "example": "stocks-venue-l2" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "limit", "in": "query", "description": "Rows per page (default 1,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of 1s quotes.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Preview-Limit": { "$ref": "#/components/headers/X-Preview-Limit" }, "X-Preview-From": { "$ref": "#/components/headers/X-Preview-From" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/l2/{source}/{ticker}": { "get": { "operationId": "getL2", "summary": "L2 1s top of book for one symbol (billed)", "description": "1s top of book of one ticker (best bid and offer: price, shares, orders), replayed from the L3 book, every published session; a row for each second whose top changed. Billed like 1s bars: one row is one bar.", "tags": [ "l2" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The L2 dataset id; `/api/v1/sources` lists them under `l2`.", "schema": { "type": "string" }, "example": "stocks-venue-l2" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "date", "in": "query", "description": "One trading session, `YYYY-MM-DD`; a session not published is a 404.", "schema": { "type": "string", "format": "date" } }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page (default 1,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "description": "`X-Next-Cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of 1s quotes.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/mbp/{source}/{ticker}": { "get": { "operationId": "getSampleMbp", "summary": "Free depth sample for one symbol", "description": "Free, no key: the first 1,000 rows after 09:30 ET of the newest session held; no paging (`start`, `end`, `cursor` answer 400).", "tags": [ "sample" ], "security": [], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The depth dataset id; `/api/v1/sources` lists them under `mbp`.", "schema": { "type": "string" }, "example": "stocks-venue-mbp" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "limit", "in": "query", "description": "Events per page (default 10,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } }, { "name": "depth", "in": "query", "description": "Omit for every price-level update; `1` for the top of book at each event that changed it. Other values answer 400.", "schema": { "type": "integer", "enum": [ 1 ] } } ], "responses": { "200": { "description": "A page of depth updates (or quotes, depth=1).", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Preview-Limit": { "$ref": "#/components/headers/X-Preview-Limit" }, "X-Preview-From": { "$ref": "#/components/headers/X-Preview-From" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/mbp/{source}/{ticker}": { "get": { "operationId": "getMbp", "summary": "Venue depth (market by price) for one symbol (billed)", "description": "Market by price of one ticker: every price-level change at full depth with nanosecond timestamps (`timestamp`, `sequence`, `side`, `price`, `size`, `flags`, `orders`), or with `depth=1` the top of book after each event that changed it. Billed at 10 rows per bar, in blocks of 1,000 rows.", "tags": [ "depth" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "The depth dataset id; `/api/v1/sources` lists them under `mbp`.", "schema": { "type": "string" }, "example": "stocks-venue-mbp" }, { "name": "ticker", "in": "path", "required": true, "description": "Symbol to fetch.", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Events per page (default 10,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "description": "`X-Next-Cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } }, { "name": "depth", "in": "query", "description": "Omit for every price-level update; `1` for the top of book at each event that changed it. Other values answer 400.", "schema": { "type": "integer", "enum": [ 1 ] } } ], "responses": { "200": { "description": "A page of depth updates (or quotes, depth=1).", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/funding": { "get": { "operationId": "getFunding", "summary": "Funding rates of one perpetual (billed)", "description": "Every funding event of one crypto perpetual, oldest first: `timestamp`, `rate` (the fraction paid by longs to shorts, negative when shorts pay) and `interval_h`. Billed like bars: one row is one bar.", "tags": [ "funding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "One perpetual, as `/api/v1/symbols` lists it (`ticker` works too).", "schema": { "type": "string" }, "example": "BTCUSDT" }, { "name": "source", "in": "query", "description": "Optional while one source carries funding (`crypto-futures`).", "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page (default 1,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "description": "`X-Next-Cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of funding events.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/prices": { "get": { "operationId": "getPerpPrices", "summary": "Mark, index or premium prices of one perpetual (billed)", "description": "1m OHLC of one crypto perpetual's mark price, index price or premium index, oldest first: `timestamp` (the minute's open), `open`, `high`, `low`, `close`. Billed like bars: one row is one bar.", "tags": [ "funding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "One perpetual, as `/api/v1/symbols` lists it (`ticker` works too).", "schema": { "type": "string" }, "example": "BTCUSDT" }, { "name": "kind", "in": "query", "required": true, "description": "`mark`, `index` or `premium` (the premium index).", "schema": { "type": "string", "enum": [ "mark", "index", "premium" ] }, "example": "mark" }, { "name": "source", "in": "query", "description": "Optional while one source carries funding (`crypto-futures`).", "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page (default 1,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "description": "`X-Next-Cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of 1m prices.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/open-interest": { "get": { "operationId": "getOpenInterest", "summary": "Open interest and long/short ratios of one perpetual (billed)", "description": "5-minute snapshots of one crypto perpetual, oldest first: `timestamp`, `open_interest` (contracts), `open_interest_value` (quote currency), `top_trader_account_ratio`, `top_trader_position_ratio`, `account_ratio`, `taker_buy_sell_ratio` (null where missing). Billed like bars: one row is one bar.", "tags": [ "funding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "One perpetual, as `/api/v1/symbols` lists it (`ticker` works too).", "schema": { "type": "string" }, "example": "BTCUSDT" }, { "name": "source", "in": "query", "description": "Optional while one source carries funding (`crypto-futures`).", "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page (default 1,000, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "description": "`X-Next-Cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "A page of 5m snapshots.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" }, "X-Bars-Charged": { "$ref": "#/components/headers/X-Bars-Charged" }, "X-Limit-Clamped": { "$ref": "#/components/headers/X-Limit-Clamped" }, "X-Query-Ms": { "$ref": "#/components/headers/X-Query-Ms" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/query/v1/corporate-actions": { "get": { "operationId": "getCorporateActions", "summary": "Splits, dividends, symbol changes and mergers (free with a key)", "description": "Every corporate action of the asked equities whose date (`ex_date`, or `process_date` when the action has none) is in `[start, end]`, by symbol then date. No paging. Free with any key.", "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "One or more tickers, comma-separated (at most 50).", "schema": { "type": "string" }, "example": "AAPL" }, { "name": "source", "in": "query", "description": "Optional while one source publishes corporate actions (`stocks`).", "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Inclusive event-time start.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Inclusive event-time end.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response encoding (not `mbt1`).", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "parquet" ], "default": "jsonl" } } ], "responses": { "200": { "description": "The actions, as `formats/corporate_actions.yaml` lists their columns.", "headers": { "X-Row-Count": { "$ref": "#/components/headers/X-Row-Count" }, "X-Format": { "$ref": "#/components/headers/X-Format" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Data-Through": { "$ref": "#/components/headers/X-Data-Through" } }, "content": { "application/vnd.apache.arrow.stream": { "schema": { "type": "string", "format": "binary", "description": "`format=arrow`. Accept: application/vnd.apache.arrow.stream" } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "`format=csv`; timestamps rfc3339. Accept: text/csv Header row included." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BarsEnvelope", "description": "`format=json`; timestamps rfc3339. Accept: application/json" } }, "application/x-ndjson": { "schema": { "type": "string", "description": "`format=jsonl` (default); timestamps rfc3339. Accept: application/x-ndjson, application/jsonl One JSON bar object per line, oldest first." } }, "application/vnd.apache.parquet": { "schema": { "type": "string", "format": "binary", "description": "`format=parquet`. Accept: application/vnd.apache.parquet, application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/sources": { "get": { "operationId": "listSources", "summary": "published sources under this root, and the ids serving l3, l2, mbp, funding, prices, open_interest and corporate_actions", "tags": [ "catalogue" ], "parameters": [], "responses": { "200": { "description": "published sources under this root, and the ids serving l3, l2, mbp, funding, prices, open_interest and corporate_actions", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "string" } }, "l3": { "type": "array", "items": { "type": "string" } }, "l2": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/timeframes": { "get": { "operationId": "listTimeframes", "summary": "timeframes for one source", "tags": [ "catalogue" ], "parameters": [ { "$ref": "#/components/parameters/source" } ], "responses": { "200": { "description": "timeframes for one source", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": [ "string", "null" ] }, "timeframes": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/symbols": { "get": { "operationId": "listSymbols", "summary": "symbol index for one source + timeframe; prefix, limit", "tags": [ "catalogue" ], "parameters": [ { "$ref": "#/components/parameters/source" }, { "name": "timeframe", "in": "query", "description": "Bar timeframe, e.g. `1s`, `1m`, `1h`, `1d`. Required. Aliases: `timeframes`, `tf`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "required": true }, { "name": "prefix", "in": "query", "description": "Only symbols starting with this, e.g. an option chain `SPY2503`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows to return, at most 20,000 (the default).", "schema": { "type": "integer", "minimum": 0, "maximum": 20000 } } ], "responses": { "200": { "description": "symbol index for one source + timeframe; prefix, limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbols": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer", "description": "Every match." }, "truncated": { "type": "boolean", "description": "True when the 20,000-row cap cut `symbols` short; narrow it with `prefix`." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/stats": { "get": { "operationId": "getStats", "summary": "candle, symbol, and byte counts from the symbol index", "tags": [ "catalogue" ], "parameters": [], "responses": { "200": { "description": "candle, symbol, and byte counts from the symbol index", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object" } }, "l3": { "type": "array", "items": { "type": "object" } }, "l2": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/schema": { "get": { "operationId": "getSchema", "summary": "bars columns and HTTP output encodings", "tags": [ "catalogue" ], "parameters": [], "responses": { "200": { "description": "bars columns and HTTP output encodings", "content": { "application/json": { "schema": { "type": "object", "properties": { "bars": { "type": "object" }, "outputs": { "type": "array", "items": { "type": "object" } }, "default_format": { "type": "string" }, "default_limit": { "type": "integer" }, "max_limit": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api": { "get": { "operationId": "index", "summary": "API index: endpoints, formats, limits, bars schema version.", "tags": [ "catalogue" ], "responses": { "200": { "description": "Self-describing index.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1": { "get": { "operationId": "indexV1", "summary": "API index: endpoints, formats, limits, bars schema version.", "tags": [ "catalogue" ], "responses": { "200": { "description": "Self-describing index.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/healthz": { "get": { "operationId": "healthz", "summary": "ok", "tags": [ "catalogue" ], "responses": { "200": { "description": "Service healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "catalog": { "type": "object" }, "cold": { "type": "object" } } } } } }, "503": { "description": "Degraded: the catalog or a cold tier did not load.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key from the dashboard." } }, "parameters": { "between": { "name": "between", "in": "query", "description": "Time range as `between=START,END`. Mutually exclusive with start/end.", "schema": { "type": "string" } }, "start": { "name": "start", "in": "query", "description": "Inclusive range start (RFC 3339, or a bare `YYYY-MM-DD` date). Aliases: `from`, `begin`", "schema": { "type": "string" }, "examples": { "date": { "value": "2024-01-02" }, "rfc3339": { "value": "2024-01-02T14:30:00Z" } } }, "end": { "name": "end", "in": "query", "description": "Inclusive range end (a bare date means that whole UTC day). Aliases: `to`, `until`", "schema": { "type": "string" }, "examples": { "date": { "value": "2024-01-02" }, "rfc3339": { "value": "2024-01-02T14:30:00Z" } } }, "format": { "name": "format", "in": "query", "description": "Response encoding; each value's media type is listed under the 200 response. On `/api/` it is the only way to choose one; on `/query/` it overrides the `Accept` header. Aliases: `fmt`", "schema": { "type": "string", "enum": [ "arrow", "csv", "json", "jsonl", "mbt1", "parquet" ], "default": "jsonl" } }, "ticker": { "name": "ticker", "in": "query", "description": "Symbol(s) to fetch. Required (or use the path form). Comma-separated. Aliases: `tickers`, `symbol`, `symbols`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, "timeframe": { "name": "timeframe", "in": "query", "description": "Bar timeframe, e.g. `1s`, `1m`, `1h`, `1d`. Required. Aliases: `timeframes`, `tf`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, "adjust": { "name": "adjust", "in": "query", "description": "Equities only: `raw` (default, prices as traded), `splits` (split-adjusted) or `all` (splits and cash dividends); see [Corporate actions](/docs/corporate-actions). Aliases: `adjustment`", "schema": { "type": "string", "enum": [ "raw", "splits", "all" ], "default": "raw" } }, "columns": { "name": "columns", "in": "query", "description": "Restrict output to these bars columns (comma-separated). Aliases: `column`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, "cursor": { "name": "cursor", "in": "query", "description": "Keyset pagination token from a prior response's `X-Next-Cursor`.", "schema": { "type": "string" } }, "source": { "name": "source", "in": "query", "description": "Dataset id (`/v1/sources` lists them), e.g. `stocks`. Aliases: `sources`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, "limit": { "name": "limit", "in": "query", "description": "Max rows. Default 1000; `0`/`all`/`none` means the maximum, 100000.", "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000 }, { "type": "string", "enum": [ "all", "none" ] } ], "default": 1000 } } }, "schemas": { "Bar": { "type": "object", "description": "One OHLCV bar. Prices are decoded floats (stored ×1000000); `timestamp` is the bar's open time and covers [timestamp, timestamp + timeframe).", "properties": { "symbol": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "description": "bar open time" }, "symbol_id": { "type": "integer" }, "open": { "type": "number" }, "high": { "type": "number" }, "low": { "type": "number" }, "close": { "type": "number" }, "vwap": { "type": [ "number", "null" ], "description": "volume-weighted average price as reported upstream, null when not reported" }, "volume": { "type": "number" }, "trade_count": { "type": "integer" }, "is_gap": { "type": "boolean" }, "gap_fill_method": { "type": "integer" } }, "required": [ "symbol", "timestamp", "symbol_id", "open", "high", "low", "close", "volume", "trade_count", "is_gap", "gap_fill_method" ] }, "BarsEnvelope": { "type": "object", "description": "`format=json`: one document wrapping the page.", "properties": { "bars": { "type": "array", "items": { "$ref": "#/components/schemas/Bar" } }, "count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "bars", "count" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } }, "headers": { "X-Row-Count": { "description": "Rows in this page.", "schema": { "type": "integer" } }, "X-Format": { "description": "The `format=` actually used.", "schema": { "type": "string" } }, "X-Next-Cursor": { "description": "Keyset token for the next page; absent on the last page.", "schema": { "type": "string" } }, "Link": { "description": "The next page as `; rel=\"next\"`.", "schema": { "type": "string" } }, "X-Data-Through": { "description": "The newest bar held for this ticker and timeframe (RFC 3339): tells \"no bars yet\" from \"no bars there\".", "schema": { "type": "string" } }, "X-Bars-Charged": { "description": "Bars billed for this response: rows rounded up to a block of 100; 0 for an empty page.", "schema": { "type": "integer" } }, "X-Limit-Clamped": { "description": "Present when `limit` asked for more rows than the balance pays for: the row cap actually applied.", "schema": { "type": "integer" } }, "X-Query-Ms": { "description": "Server-side wall time in milliseconds.", "schema": { "type": "integer" } }, "X-Preview-Limit": { "description": "The latest-bars view's size: with no `start`/`end`/`cursor` the sample returns at most this many newest bars, and no cursor.", "schema": { "type": "integer" } }, "X-Preview-From": { "description": "The oldest instant the free sample serves (RFC 3339); earlier `start` values are clamped to it.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "Bad request: unknown format/column, bad timestamp, limit over the maximum, missing ticker or timeframe." }, "Unauthorized": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "Missing or invalid API key." }, "PaymentRequired": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "Out of bars for this account (or for this page)." }, "Forbidden": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "A browser-session request sent from another site (`/query/` only); send `Authorization: Bearer `." }, "NotFound": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "No such source, symbol, or timeframe." }, "TooManyRequests": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "Rate limited. Back off and retry. A 429 from the edge may come without the JSON body.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "ServerError": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "Internal error." }, "BadGateway": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "The query service is unreachable from the edge." }, "Unavailable": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "Temporarily unavailable: the server is shedding load (over its concurrency limit), or the catalog / a storage tier is not serving.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "GatewayTimeout": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "description": "The request took too long and was cancelled." } } } }