How to page past the Binance API klines limit of 1,000

What the limit parameter actually returns

The limit parameter caps how many candles one response may contain, and its two numbers explain most of the confusion around this endpoint: the default limit of 500 applies when you don’t send the parameter at all, and 1,000 is the hard ceiling — the docs list it plainly as “Default: 500; Maximum: 1000.” So a bare request quietly gives you half of what the endpoint can return, which is why the first fix for “not enough candles” is simply asking for the maximum.

On the Spot API there is no reason not to. The klines call costs a flat weight of 2 regardless of limit, so a request for 1,000 candles is priced the same as a request for 10 — asking for less than the maximum while paging is just paying the same weight for less data. The limit per request interacts with the time parameters in one more way worth knowing: without startTime and endTime, the endpoint returns the most recent candles, not the oldest. That default is what you want for a live dashboard and exactly what you don’t want for a backfill.

Two smaller notes from the klines endpoint documentation save real debugging time. First, candles are uniquely identified by their open time — that identity is what pagination and deduplication should key on. Second, the endpoint accepts a timeZone parameter that shifts how intervals are bucketed, but startTime and endTime are always interpreted in UTC regardless — mixing those two up produces off-by-hours ranges that look like missing data.

How to pull a long date range in chunks

The pattern is a cursor loop over the startTime and endTime parameters: request up to 1,000 candles from the cursor, store them, move the cursor just past the open time of the last candle received, and repeat until the endpoint has nothing left in your range. The one design decision that separates a robust pager from a fragile one is how you advance. Stepping by a fixed amount — “add 1,000 intervals” — assumes the data has no holes, and it does have holes: maintenance windows and delistings leave gaps, and a fixed step either re-downloads overlaps or silently skips past data. Advancing from the last candle actually returned survives all of that.

Here is a complete pager built on those rules — an example klines request loop you can run as-is, with no API key required:

import time, requests

BASE = "https://api.binance.com"

def fetch_history(symbol, interval, start_ms, end_ms):
    out, cursor = [], start_ms
    while cursor < end_ms:
        resp = requests.get(f"{BASE}/api/v3/klines", params={
            "symbol": symbol, "interval": interval,
            "startTime": cursor, "endTime": end_ms, "limit": 1000})
        if resp.status_code == 429:                      # back off, then retry
            time.sleep(int(resp.headers.get("Retry-After", "1")))
            continue
        batch = resp.json()
        if not batch:                                    # nothing left in range
            break
        for k in batch:
            if k[6] > time.time() * 1000:                # close time in the future:
                continue                                 # drop the still-forming candle
            if not out or k[0] > out[-1][0]:             # dedupe by open time
                out.append(k)
        cursor = batch[-1][0] + 1                        # advance past last OPEN time
    return out

What to look at in the behavior: the cursor moves to last open time + 1 ms, which is safe because open time is the candle’s identity; the final candle of a live range is dropped when its close time hasn’t arrived yet, because a still-forming candle will change after you store it; and a 429 is handled by honoring Retry-After rather than continuing to send requests.

Now the arithmetic that makes this practical. A year of 1-minute historical klines is 525,600 candles — 526 requests at the 1,000 ceiling, or about 1,050 weight at 2 per call. Against the Spot API’s 6,000-per-minute budget, that fits inside a single minute’s allowance with room to spare. We measured the full version of that job on our own network: the complete 1m history of BTCUSDT — roughly 4.7 million candles, about 4,710 requests at limit=1000 — costs 9,420 weight, around a minute and a half of one address's budget. Wall-clock time then depends entirely on concurrency: a sequential pager like the one above takes about 25 minutes at 3 requests per second, while 16 concurrent connections through one dedicated address finish in about 100 seconds with zero 429s — the full benchmark is here. For a single pair, the API is not the bottleneck people expect.

Which endpoints share the same cap

The 500-default, 1,000-maximum pair is not unique to candles — it is a common pattern across the spot market-data family, so the same pager works across it. The spot klines endpoint has a chart-oriented twin, uiKlines, with the same parameters, the same cap, and the same open-time identity. Recent and aggregate trades (/api/v3/trades, /api/v3/aggTrades) carry the identical “Default 500; max 1000” line in the docs, with aggTrades adding its own constraint: a startTime/endTime window there must span less than one hour.

Futures are where the constants quietly change, and copy-pasted spot code gets the limits wrong. The USDⓈ-M klines endpoint on fapi.binance.com accepts up to 1,500 candles per request — a higher ceiling than spot — but prices the call by size: the request weight grows with limit instead of staying flat. The pager logic transfers unchanged; the two constants (page size and per-call cost) must come from the futures endpoint table, not from spot assumptions. The general rule from our guide to Binance API rate limits applies here in miniature: read the caps for the REST v3 klines endpoint from the documentation of the API you’re actually calling, and let your code take page size as a parameter rather than a fixed belief.

When bulk data dumps beat the API

Paging is the right tool for one pair and a bounded range. It stops being the right tool when the job is “the whole market, all of history” — and Binance itself provides the alternative. The official public archives at data.binance.vision (maintained under the binance-public-data project) serve historical market data as plain ZIP files: monthly and daily dumps of klines, trades, and aggregate trades for spot and both futures markets, each with a SHA-256 checksum file alongside. Downloading a year of a pair’s candles becomes one HTTP GET of a monthly archive instead of hundreds of paged requests — and downloading the whole market becomes a wget loop instead of millions of API calls that would exceed any practical per-IP request budget.

Two properties of the archives matter for pipeline design. Freshness: the previous day’s files appear a few minutes after 00:00 UTC, so archives always trail the present — the standard production pattern is backfill from the archives, then top up the live tail through the API pager above. Mutability: Binance notes that archived files may be updated later when issues are discovered, so long-lived datasets should re-verify checksums rather than assume immutability.

One boundary completes the picture: historical order book data is the gap in both tools. The REST depth endpoint returns only the current snapshot — there is no “depth as of last Tuesday” call — and the public spot archives don’t include order book history either. If your research needs historical depth, you record it yourself from the WebSocket streams as it happens, or you buy it from specialized data vendors. Knowing that boundary before designing a backtest saves weeks.

Where does this leave the API-versus-archives decision? Backfill any serious breadth from the archives; use the pager for single-pair jobs and for the live tail the archives haven’t caught up to. The place per-IP budgets genuinely bite is the third workload — continuous multi-pair polling on top of that backfill, where hundreds of symbols compete for one address’s 6,000 weight per minute. That is an egress problem rather than a pagination problem: spreading the polling across dedicated addresses gives every worker its own budget, and it is exactly what our proxies for Binance provide — dedicated proxies starting at one IP, plus bulk plans with thousands of IPs, IP whitelisting, and HTTP, HTTPS, SOCKS4, and SOCKS5 access.

FAQ

What is the maximum number of candles per request?

1,000 on the Spot API, with 500 returned by default when you omit limit. USDⓈ-M futures allow up to 1,500 per request but price the call by size — higher limit, higher weight — while spot charges a flat 2 regardless. On spot there’s no reason to page with anything below the maximum; on futures, check the weight table first.