getBlocksWithLimit

Returns a list of confirmed blocks starting at the given slot

Common use cases

Exchange deposit scanning	Track incoming SOL/token deposits by polling blocks sequentially from last processed slot. Production-proven approach used by major exchanges, more reliable than WebSocket subscriptions which disconnect frequently.
Historical block backfilling	Retrieve large ranges of historical blocks for analytics or data migration. Use larger limit values (10k-50k) with finalized commitment for archival data that won't reorganize.
Indexer block ingestion	Continuously poll for new blocks starting from current slot to index blockchain data. Combine with getBlock to fetch full block details for each returned slot number.
Slot-to-blockHeight lookup	Perform binary search across block ranges to find the slot corresponding to a specific block height. Useful for mapping between slot-based and height-based references.

Parameters

start slot (u64, required)

Start slot

limit (u64, optional)

Limit (must be no more than 500,000 blocks higher than the start_slot)

options (object, optional)

Configuration object

Fields:

• commitment (string): The commitment describes how finalized a block is at that point in time. See Configuring State Commitment.
  • "processed" is not supported

Request

cURL

curl https://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlocksWithLimit",
  "params": [
    5,
    3
  ],
  {
    "commitment": "finalized"
  }
}'

JavaScript

// Using fetch
const response = await fetch('https://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlocksWithLimit",
  "params": [
    5,
    3
  ],
  {
    "commitment": "finalized"
  }
})
});
const data = await response.json();
console.log(data);

Python

import requests
import json

url = 'https://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY'
headers = {'Content-Type': 'application/json'}
data = {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlocksWithLimit",
  "params": [
    5,
    3
  ],
  {
    "commitment": "finalized"
  }
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())

Network Selection

Replace mainnet with devnet in the URL to query devnet instead.

Response

{
  "jsonrpc": "2.0",
  "result": [5, 6, 7],
  "id": 1
}

Response Fields

Return value: array

An array of u64 integers listing confirmed blocks starting at start_slot for up to limit blocks, inclusive.

FAQ and Troubleshooting

Why does getBlocksWithLimit return fewer slots than my limit parameter?

Returns only slots that produced blocks. If there are skipped slots in the range, fewer results are returned. Also returns fewer if you reach the latest finalized slot before hitting the limit.

Should I use getBlocks or getBlocksWithLimit for sequential scanning?

Use getBlocksWithLimit for simpler pagination - just provide start slot and count. Use getBlocks when you know the exact end slot. getBlocksWithLimit is preferred for continuous scanning where you increment from the last processed slot.

What's the best limit value for real-time block processing?

Use 100-500 for near-real-time processing to minimize latency. Larger limits (10k-50k) work for historical backfilling where latency is less critical. Major exchanges use small batches for deposit tracking.

Why does my call fail with "limit exceeds maximum"?

The maximum limit is 500,000 blocks. Split larger ranges into multiple calls with 500k batches. This constraint is enforced server-side via MAX_GET_CONFIRMED_BLOCKS_RANGE constant.

Can I use processed commitment with getBlocksWithLimit?

No, only confirmed and finalized commitments are supported. The method requires data stability - blocks at processed commitment may reorganize. Use confirmed for near-real-time or finalized for irreversible data.

Related Methods

getBlocks
Returns slots for a range between start and end slots. getBlocksWithLimit is similar but uses start + limit instead of start + end, making it simpler for sequential pagination without calculating end slots.

getBlock
Fetches complete block data (transactions, rewards, metadata) for a specific slot. Always used after getBlocksWithLimit - first get slot numbers, then fetch full block details for each slot.

getSlot
Returns current slot at specified commitment level. Use before getBlocksWithLimit to determine starting point for scanning from current tip, or to validate that returned slots are up-to-date.

blockSubscribe
WebSocket alternative for real-time block notifications. getBlocksWithLimit polling is more robust for production use - exchanges prefer it over WebSocket due to connection stability issues.

getBlockHeight
Returns block height instead of slot number. Use with getBlocksWithLimit for slot-to-height conversion via binary search, when working with height-based references in applications.

External Resources

• Solana Official Documentation
• Solana RPC HTTP Methods - Official Solana RPC documentation covering all HTTP methods including getBlocksWithLimit parameters, response format, and commitment levels.
• Solana Commitment Levels - Official guide to Solana's commitment levels (processed, confirmed, finalized). Essential for understanding which commitment to use with getBlocksWithLimit for different use cases.