Paginate with Upper-Bound Limit

Use pagination with an upper-bound limit for queries that return 200 or more records. To paginate with an upper-bound limit, use the upperBound argument in the initial query or, starting in API v60.0, in a subsequent query.

When you use an upper-bound limit, you can paginate up to the upperBound number of records.

• The first argument corresponds to the batch size to query and subsequently to retrieve the next batch in cases when there are more records than a certain threshold. first can have a value from 200 to 2000 only.
• The after argument is a cursor used to page through the result set. Omit the argument or provide a null value to start at the beginning of the result set. Use after following your initial query to get the next batch of results.
• The upperBound argument specifies a limit for the number of records to retrieve. We recommend using a high default value for your query. In API v59.0, the upperBound argument must be specified in the initial query. In API v60.0 and later, the upperBound argument can be specified in a subsequent query, allowing you to switch from record connection pagination to upper-bound limit pagination.

This example uses the upperBound limit.

An example response looks like this.

After using the upper-bound limit to send an initial query, retrieve the next batch of results. To retrieve the next batch, use the first and after arguments.

If you don't include the upperBound argument initially, the query applies simple pagination using relay record connections. In API v60.0 and later, you can use the upperBound argument in a subsequent query to retrieve more than 4,000 records overall. This means you can switch from using record connection pagination to using upper-bound limit pagination for the same query.

Here’s an example where we initially query a batch of 2,000 accounts using the first argument.

Here's an example result of the query with simple pagination.

After an initial relay record connections query, retrieve the next batch of results and include the upperBound argument in a subsequent query.

Continuing with the example above, we query the next batch of results using the first, after, and upperBound arguments, switching to upper-bound limit pagination. The after argument uses the endCursor value from the result of the initial query. The upperBound argument specifies the limit for the number of records to retrieve. Even though the initial query requested a batch of 2,000 records, the subsequent upper-bound limit pagination allows the query to return up to 5,000 records.

The example result looks like this.

Then you can make subsequent queries using first and after arguments to page through more results up to the upper-bound limit.

You can page through child records by querying a parent record with an upperBound argument. When the parent query uses the upperBound argument, the child query must use this argument as well. You can also page through child records using the upperBound argument when the parent query doesn't use the upperBound argument. Paging on the parent and children records at the same time isn't supported. Keep in mind that paging through child relationships with large upper-bound limits can have performance implications.

When querying with the upperBound argument, consider these limitations.

• You must query 200 records or more. For example, set first:200 with upperBound:5000. To query fewer than 200 records, use simple pagination without an upper-bound limit.
• Paging through child relationships with large upper-bound limits can have performance implications.

SOAP API Developer Guide: queryMore()