Cairo RPC ↔ Event Indexer: Query Bounding and Pagination Interoperability

Question

Cairo RPC ↔ Event Indexer Pagination
The Cairo blockchain exposes an RPC endpoint for querying events that accepts a block range to bound the query and pagination parameters (cursor and limit) for incremental retrieval. Documentation indicates that the cursor is a base64‑encoded string representing the last retrieved event’s position, but it does not state whether the cursor is inclusive or exclusive, leading to ambiguity when chaining pages. Additionally, the maximum value for the limit parameter is not specified; empirical observations suggest requests with limit > 1000 may be throttled or truncated by the indexer service. The API returns a next_cursor field when more results are available, yet its format and semantics are not fully documented, complicating automated pagination pipelines. Understanding these behaviors is essential for building reliable event‑driven integrations.
Unresolved questions:

Is the cursor returned by the /events endpoint inclusive of the last event or exclusive?
What is the maximum safe value for the limit parameter before the indexer truncates or throttles the response?
Does the next_cursor field consistently represent the position after the last returned event across different indexer implementations?

Tasadduq Burney · Answer

Answer
The cursor returned by the Cairo RPC /events endpoint is exclusive: it encodes the position immediately after the last event returned in the current page, so the next request should start with that cursor to avoid duplicates.
Based on empirical observations from similar indexers, a safe limit is roughly 500–1000 events per request; values significantly above 1000 often trigger throttling or truncation, though the exact ceiling is not documented.
The next_cursor field is intended to represent that exclusive position after the last returned event, and this behavior appears consistent across the main StarkNet indexer implementations, but minor variations could exist in custom forks.
Verification steps

Request a small page (e.g., limit=5) from the /events endpoint with a known block range and record the returned events and the next_cursor.
Use that cursor as the start position for a second request with the same limit and block range; compare the first event of the second page to the last event of the first page. If they differ, the cursor is exclusive; if they match, it is inclusive.
Gradually increase the limit (e.g., 100, 500, 1000, 1500) and observe whether responses are truncated, return fewer events than requested, or produce error/throttle responses to estimate the safe maximum.
Repeat the above against a different indexer instance (e.g., a public testnet node vs. a private indexer) to check consistency of next_cursor semantics.

To confirm whether the observed consistency holds for your setup, please specify which indexer implementation you are querying (public StarkNet node, a known fork, or a custom deployment).

Cairo RPC ↔ Event Indexer: Query Bounding and Pagination Interoperability

Cairo RPC ↔ Event Indexer Pagination

1 answer

Answer

Verification steps

Your perspective belongs here.

0 question comments