getBlocksWithLimit — Solana RPC Method

getBlocksWithLimit returns a list of confirmed block slot numbers starting at a given slot, up to a maximum count. Unlike getBlocks, which takes a slot range, this method takes a count — making it ideal for paginated ledger scanning.

Parameters

Request

curl -X POST https://api.mainnet-beta.solana.com \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBlocksWithLimit",
    "params": [311857920, 5]
  }'

TypeScript (@solana/kit)

import { createSolanaRpc } from "@solana/kit";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
const blocks = await rpc
  .getBlocksWithLimit(311857920n, 5n)
  .send();

console.log(blocks);
// e.g. [311857920, 311857921, 311857923, 311857924, 311857925]

Response

{
  "jsonrpc": "2.0",
  "result": [311857920, 311857921, 311857923, 311857924, 311857925],
  "id": 1
}

Common errors

• Limit too large — limit must not exceed 500,000. A larger value returns an error.
• Slots too old — if the starting slot is beyond the node’s retained ledger data, fewer results than limit may be returned.
• processed not supported — using commitment: "processed" returns an error. Use confirmed or finalized.

Performance

The method returns up to limit slot numbers. The actual response ends when either limit blocks are found or the node runs out of available ledger data. For scanning large portions of the ledger, paginate by taking the last slot in the response, adding 1, and using it as the next start_slot.

FAQ

How do I paginate through all blocks? Take the last element of the returned array, add 1, and pass it as start_slot in the next call. Repeat until the result is empty or shorter than limit.

What is the difference between getBlocksWithLimit and getBlocks? getBlocks requires an end slot and returns all blocks in that range. getBlocksWithLimit takes a count and returns that many blocks starting from a slot. Use getBlocksWithLimit for fixed-size pagination.

Why might the result contain fewer blocks than the limit? Either the node’s available ledger data ran out before reaching the limit, or there are simply not enough blocks between start_slot and the latest slot.

Does this skip slots that had no block? Yes. Only slots where a block was produced appear in the result. Skipped slots are excluded.

Parameters

Updated: 2026-10-19