Paginate with Upper Bound Limit

Use pagination with an upper bound limit for queries that return more than 2000 records. To use an upper bound limit, use the upperBound argument.

When you use an upper bound limit, you can paginate up to the upperBound number of records. The upperBound argument acts as LIMIT on the initial SOQL query.

• 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 that specifies upperBound.
• The upperBound argument specifies a limit for the number of records to retrieve. We recommend using a high default value for your query.

The following examples use LIMIT and OFFSET for pagination when the offset is less than 2000.

The previous query corresponds to this SOQL statement.

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.

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.
• When the parent query doesn't use the upperBound argument, the child query can optionally use the upperBound argument. However, if the parent query uses the upperBound argument, the child query must use this argument as well.
• Results are dropped only in rare cases when last page results are more than the total number you request with upperBound.

SOAP API Developer Guide: queryMore()

SOQL and SOSL Reference: LIMIT

SOQL and SOSL Reference: OFFSET