Why is Formance Ledger's pageSize limited to 100?
Last updated: January 7, 2026
The Formance Ledger API limits the pageSize parameter to a default maximum of 100 records per request. This article explains the reasoning behind the limit, the trade-offs involved, and how to configure it for specific use-cases like internal demos or large-scale data retrieval.
What is pageSize ?
The pageSize is a query parameter used in paginated API requests that determines how many records (e.g., accounts, transactions) are returned in a single API call.
Example:
GET /ledger/transactions?pageSize=100Why Is It Limited to 100?
Reason | Description |
Performance Protection | Prevents large, slow queries from degrading server performance. |
Avoids Timeouts | Helps avoid request timeouts through load balancers, proxies, or the backend itself. |
Fair Usage | Ensures one client doesn't monopolize server resources in multi-tenant environments. |
Pagination Stability | Reduces the risk of data inconsistency during long pagination sequences. |
Configuring a Higher pageSize
In some cases (e.g. internal demos, data exports), you may want to fetch more than 100 records at a time. There is an environment variable that allows us to increase the maximum allowed pageSize for the Ledger process.
You can't override the max page size via the API
Note: The default remains 100 unless explicitly changed.
On the v1 endpoints, the max page size is hardcoded to 1000.
On the v2 endpoints, the max page size is taken from the config (service flags or env var), and is by default, defined to 100.
⚠ Considerations Before Increasing
Risk | Impact |
Timeouts | Larger payloads may hit gateway or reverse proxy timeouts. |
Memory Usage | Fetching too many records in one call can spike memory usage. |
Slower Pagination | Larger responses take longer to parse and transmit, possibly degrading client performance. |