Developer··9 min read

Kalshi Historical Data: API, Candles & Archive Cutoffs

Find Kalshi historical markets, trades and candles with current archive cutoffs, verified public reads, null-price examples and an offline Python request planner.

Kalshi Historical Data: API, Candles & Archive Cutoffs
On this page

Kalshi historical data is available through separate public archive routes for older markets, trades and candlesticks. Start by identifying the record type and reading its current archive cutoff. A successful request to a live endpoint does not establish that it includes every older record.

Reviewed November 21, 2026 (Pacific time), using current official documentation and bounded unauthenticated reads recorded on November 22 UTC. This guide concerns prediction-market data, not the separate perpetual-futures API. It does not retrieve an account’s fills, orders or positions, and it does not place trades.

Choose the historical dataset before downloading

Research questionData to inspectWhat it cannot establish by itself
What did a settled contract ask?Market metadata and settlement rulesThe price available for an earlier order
What transactions occurred?Public tradesEvery resting order or your account’s participation
How did price summaries change?Market candlesticksFull intraperiod sequence or depth
What could a large order have filled?Timestamped book depth and execution assumptionsA conclusion from candle closes alone
What happened in my account?Authorized account-specific recordsAn answer from public market trades

Kalshi’s historical-data overview explains the live/archive split. Events and series remain available through their original routes, while nested market lists can omit archived markets. Use the historical market listing when researching archived contracts; its response is cursor-paginated and its filters are mutually exclusive.

Read the current cutoff instead of hard-coding an age

curl -fsSL 'https://external-api.kalshi.com/trade-api/v2/historical/cutoff'

A fresh public request at 2026-11-22 00:55:14 UTC returned HTTP 200 with this snapshot:

Cutoff fieldObserved timestampClock to preserve
market_settled_ts2026-09-22T00:00:00ZMarket settlement
trades_created_ts2026-09-22T00:00:00ZTrade fill
orders_updated_ts2026-11-07T00:00:00ZOrder cancellation or full execution
market_positions_last_updated_ts2026-09-22T00:00:00ZPosition backfill horizon

These values describe one observation, not a permanent retention policy. The cutoff reference distinguishes the clocks. A settled position can remain live until a buffered, whole-event handoff completes, so its horizon is not a guaranteed archive-visibility boundary. No account-position handoff was tested here.

For a fictional routing example, suppose a market has an August candle but settles on October 20. Under the observed September 22 market cutoff, the candle’s August date alone does not move it to the archive: the market’s settlement clock determines the candle tier. A trade filled in August follows the separate trade cutoff. Do not apply one date comparison to every record type.

Useful public routes, with the base URL kept explicit

The following paths are relative to https://external-api.kalshi.com/trade-api/v2. They are documented public data routes, distinct from account-scoped archive reads:

TaskRoute
Current partition timestampsGET /historical/cutoff
Archived market metadataGET /historical/markets
One archived marketGET /historical/markets/{ticker}
Archived market candlesGET /historical/markets/{ticker}/candlesticks
Older public transactionsGET /historical/trades

Public trades and user fills are different resources. The general historical-data overview lists both; use the endpoint-specific schema for the record you need. Signed account requests require their own authorization. See our Kalshi API guide for the broader public-data and authentication distinction.

A real bounded archive check, including a null-price candle

At 2026-11-22 00:55:41 UTC, this public listing request returned one market and a continuation cursor:

GET /historical/markets?limit=1&mve_filter=exclude

The returned ticker was KXTEMPNYCHS-26SEP2119-T71.99. Its recorded close was September 21 at 23:00 UTC and settlement was later that evening. A subsequent request for the 24 hours ending at that close, using 60-minute periods, returned HTTP 200 and one candle:

GET /historical/markets/KXTEMPNYCHS-26SEP2119-T71.99/candlesticks
  ?start_ts=1789945200&end_ts=1790031600&period_interval=60

The candle’s trade-price open, high, low, close, mean and previous fields were all null; volume was "0.00". Separately, its closing Yes bid was "0.0000" and closing Yes ask was "0.1000". A missing trade price and a numerical zero quote are different observations. This one result is not evidence that all markets have sparse candles or that a 24-hour request always returns one row.

The historical candle schema separates bid, ask and trade-price distributions. Nullable trade-price fields can represent periods without trades. Preserve the null values rather than replacing them with zero, forward-filling them silently or labeling a quote as a completed transaction.

Candle request limits: seconds, intervals and inclusive boundaries

The official live candle reference and archive reference document intervals of 1, 60 or 1440 minutes and a maximum span of 5,000 periods per request. Timestamps are Unix seconds. The archive filters select candles by their inclusive end timestamp.

For an original planning example, a 30-day one-minute span contains 43,200 minutes. Dividing it into spans no longer than 5,000 periods requires nine requests: eight spans of 5,000 minutes and one of 3,200. That is a request plan, not a promise about the number of returned candles.

Adjacent inclusive windows can share an end timestamp. Keep the original responses and reconcile duplicates using market, interval and candle-end time. If two rows with the same key disagree, preserve the conflict for review instead of silently selecting the later response. A boundary overlap should not double-count volume.

Download an offline window and reconciliation example

The standard-library Python worksheet plans that nine-request span without downloading it. Its fictional two-page fixture contains four rows but only three unique candle keys because a boundary row appears twice. It retains a null close, distinguishes a decimal zero and rejects a conflicting duplicate. It does not validate every provider field or infer whether an input dataset is complete.

Decimal strings should retain their units. A value of "0.1000" dollars is ten cents, not ten dollars. Fractional contract counts should not be truncated to integers. Keep bid/ask summaries, trade prices, volume and open interest in separate columns; adding unlike quantities does not make a more complete history.

Can candles reconstruct historical order-book data?

A candle’s open, high, low and close do not provide the quantity available at each price level or the sequence of order changes. Even a non-null trade close proves neither that your hypothetical order could have filled at that price nor that enough size was available.

For example, a fictional candle close of 0.40 cannot tell you whether one contract or 1,000 contracts were available at that price. A simulated 1,000-contract fill would require separate depth and timing assumptions. Do not turn the real example’s 0.10 ask summary into a claimed executable price for arbitrary size.

For live book reconstruction concepts, read our Kalshi WebSocket guide. That workflow is separate from a retrospective candle download and does not automatically recover snapshots that were never recorded.

Before using the download in a backtest

Record the exact market identity and rules, cutoff snapshot, retrieval time, request windows, cursors and errors. Follow pagination deliberately and set a collection budget; the one-page observation above is not a complete-market export. Keep excluded, missing and unresolved observations explicit.

Use point-in-time inputs, a time-respecting evaluation and separately modeled fees, execution and position sizing. Public historical data alone does not establish an account’s performance, a forecasting edge or a profitable strategy. Explore Alphascope for prediction-market research alongside the contract’s current source documentation.

Frequently Asked Questions

Where can I get Kalshi historical data?▾

Start with the documented public historical routes for archived market metadata, candles and trades. Read the current cutoff for the record type rather than assuming the live endpoint contains its full history.

Does a null candle close mean a zero price?▾

No. In the bounded public observation, trade-price fields were null while bid and ask summaries had numeric values. Keep missing trade prices separate from a legitimate zero quote.

Do market and trade archives use the same timestamp?▾

No. Market and candle routing uses the market settlement clock; public trades use the trade fill clock. Read the current cutoff fields because their values and windows can differ.

Can Kalshi candles prove historical order-book depth?▾

No. Candle summaries do not establish the quantity available at each level, the intraperiod order sequence or whether a hypothetical order could have filled.