API reference · History

Get candles

GET/v1/history/candles

One market's price history as candles, oldest first, paged by time.

On this page

Auth. An API token: Authorization: Bearer lb_… (create one). Signed-in web sessions work too.

Limits. One history query per call (500 a day on Free; unlimited on Builder and Standard).

Parameters

Query parameters

Name	Type	Required	Description
`ticker`	string	yes	The venue ticker or `pm_<id>`.
`period`	string	no	Seconds, or `1m`, `1h` or `1d`; default the finest stored. `periods_available` lists them.
`since`	integer	no	ms epoch; candles whose period ends at or after it.
`until`	integer	no	ms epoch; candles whose period ends at or before it.
`limit`	integer	no	Candles per page. 1 to 5000. Default `1000`.

Request

Terminal

curl "https://api.langbot.ai/v1/history/candles?ticker=SENATETX-26-R&period=1h&limit=2" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN"

Python

from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    page = await lb.candles("SENATETX-26-R", period="1h", limit=2)
    for c in page.candles:
        print(c.ts, c.close, c.volume)

TypeScript

const res = await fetch("https://api.langbot.ai/v1/history/candles?ticker=SENATETX-26-R&period=1h&limit=2", {
  headers: { Authorization: `Bearer ${process.env.LANGBOT_API_TOKEN}` },
});
console.log(await res.json());

Response

200 OK

JSON

{
  "ticker": "SENATETX-26-R",
  "venue": "kalshi",
  "period_s": 3600,
  "periods_available": [60, 3600, 86400],
  "since": null,
  "until": null,
  "count": 2,
  "candles": [
    { "ts": 1793520000000, "open": 0.27, "high": 0.28, "low": 0.26, "close": 0.27, "volume": 18210, "open_interest": 2410000, "bid_close": 0.26, "ask_close": 0.27 },
    { "ts": 1793523600000, "open": 0.27, "high": 0.27, "low": 0.26, "close": 0.265, "volume": 9930, "open_interest": 2412000, "bid_close": 0.26, "ask_close": 0.27 }
  ],
  "next_since": 1793527200000
}

ts is the end of each period. Prices are YES probabilities (0 to 1). Pass next_since back as since for the next page (null on the last). iter_candles() in the Python SDK follows the pages for you.

Errors

Status	`code`	When
404	`not_found`	The market has no candles, or none at `period`.
401	`auth_required`	No token was sent.
401	`token_invalid`	The token was not recognised (mistyped, revoked or expired).
422	`validation_error`	A parameter failed validation; `detail[].loc` names it.
429	`quota_exceeded`	Today's history queries are spent; `quota.resets_at` says when they reset.
429	`rate_limited`	Over your request budget; wait `Retry-After` seconds.

Every error body is {"detail": …, "code": "…"}; branch on code. All codes: Errors.