Understanding Paginated API in Salesforce: A Complete Guide

When working with large datasets in Salesforce, retrieving all records in a single API request is often impractical or impossible. Salesforce enforces governor limits to maintain performance and prevent system overload. To handle large volumes of data efficiently, Salesforce provides paginated APIs. In this blog, we’ll explore what paginated APIs are, why they’re important, and how to use them effectively.

What is a Paginated API?

A paginated API is an API that delivers data in chunks (pages) rather than returning the entire dataset in one response. Each page contains a subset of the records along with a pointer or token to fetch the next page.

This approach helps:

Reduce memory usage and response time
Avoid API timeout errors for large datasets
Comply with Salesforce governor limits

Why Pagination is Important in Salesforce

Salesforce APIs have limits on:

Number of records returned per query (e.g., 2,000 for REST API, 50,000 for SOQL queries in Apex)
API request size and payload size

Without pagination, trying to fetch thousands of records at once could:

Cause API failures
Increase latency
Overload the client or server

Pagination ensures efficient, reliable, and scalable data retrieval.

Types of Pagination in Salesforce

Salesforce provides different APIs that support pagination:

REST API Pagination

Salesforce REST API uses nextRecordsUrl for pagination.
When querying data via /services/data/vXX.X/query/?q=SOQL_QUERY, the response may include a nextRecordsUrl if there are more records.
You use this URL in subsequent requests to fetch the next page.

Example:

{

“totalSize”: 5000,

“done”: false,

“records”: [

{ “Id”: “0015g00000XXXX”, “Name”: “John Doe” },

{ “Id”: “0015g00000YYYY”, “Name”: “Jane Smith” }

“nextRecordsUrl”: “/services/data/v53.0/query/01g5g00000XXXXX”

}

done indicates whether more records are available.
Fetch the next page using the nextRecordsUrl.

Bulk API Pagination

Salesforce Bulk API 2.0 is designed for handling large volumes of records asynchronously.
You create a job, submit batches, and Salesforce processes them in the background.
The results can be retrieved page by page using the job ID and batch information.

Apex Pagination

Within Salesforce Apex, you can implement pagination for Visualforce pages or Lightning components.
This often involves SOQL queries with LIMIT and OFFSET clauses:

Integer pageSize = 50;

Integer pageNumber = 2;

List<Account> accounts = [SELECT Id, Name FROM Account ORDER BY Name LIMIT :pageSize OFFSET :((pageNumber-1)*pageSize)];

Apex pagination is useful for UI components displaying data in pages.

Best Practices for Paginated APIs

Use indexed fields for sorting – Improves query performance when fetching pages.
Avoid high offsets in SOQL – OFFSET can become inefficient with very large datasets. Use query cursors (nextRecordsUrl) when possible.
Set an appropriate page size – Balance between payload size and number of API calls. Salesforce REST API default is 2000 records per page.
Handle done flag properly – Always check if more pages are available.
Error handling – Retry logic for network or API errors is critical for reliable pagination.

Real-World Use Case

Suppose a company wants to export all Accounts to an external system using Salesforce REST API.

Instead of fetching 50,000+ accounts in one call, you query 2,000 records per page.
Use the nextRecordsUrl to fetch the next set until done = true.
This ensures efficient data transfer and avoids API limits.

Conclusion

Paginated APIs in Salesforce are essential for working with large datasets efficiently and safely. Whether you’re integrating Salesforce with external systems, building dashboards, or exporting data, understanding pagination mechanisms is critical for performance and reliability.

By implementing best practices, you can ensure smooth, scalable, and optimized data access while staying within Salesforce governor limits.