# Paginate with Upper-Bound Limit | AVAILABLE API VERSION | | --------------------- | | API v59.0 and later | 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. ## Use the Upper-Bound Limit in the Initial 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 if 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, you must specify the `upperBound` argument in the initial query. In API v60.0 and later, you can specify the `upperBound` argument in a subsequent query, allowing you to switch from record connection pagination to upper-bound limit pagination. This example uses the `upperBound` limit. ```sfdocs-code {"lang":"graphql", "title": "Use first and upperBound arguments", "src": "" } query RecordsWithPagination { uiapi { query { Contact (first:200, upperBound:5000) { edges { node { Id Name { value } } } totalCount pageInfo { hasNextPage endCursor } } } } } ``` An example response looks like this. ```sfdocs-code {"lang":"json", "title": "Query results after upperBound limit in initial query", "src": "" } { "data": { "uiapi": { "query": { "Contact": { "edges": [ { "node": { "Name": { "value": "Rose Gonzalez" } } }, { "node": { "Name": { "value": "Sean Forbes" } } } //More records in the result here ], "totalCount": 1034, "pageInfo": { "hasNextPage": true, "endCursor": "djI6LTE1NjE0NTE4NDc6MHI4eHgxdk5tcUM5SU1jQUVOLTE5OQ==" } } } } }, "errors": [] } ``` ## Retrieve the Next Batch After Using upperBound in the Initial Query 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. ```sfdocs-code {"lang":"graphql", "title": "Use first and after arguments", "src": "" } query RecordsWithPagination { uiapi { query { Contact (first:200, after:"djI6LTE1NjE0NTE4NDc6MHI4eHgxdk5tcUM5SU1jQUVOLTE5OQ==") { edges { node { Id Name { value } } } totalCount pageInfo { hasNextPage endCursor } } } } } ``` ## Use the Upper-Bound Limit in a Subsequent Query 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. ```sfdocs-code {"lang":"graphql", "title": "Query accounts using the first argument", "src": "" } { uiapi { query { Account(first:2000) { totalCount pageInfo { hasPreviousPage hasNextPage startCursor endCursor } edges { cursor node { Id } } } } } } ``` Here's an example result of the query with simple pagination. ```sfdocs-code {"lang":"json", "title": "Query result with record connection pagination", "src": "" } { "data": { "uiapi": { "query": { "Account": { "totalCount": 4087, "pageInfo": { "hasPreviousPage": false, "hasNextPage": true, "startCursor": "djE6MA==", "endCursor": "djE6MTk50Q==" }, "edges": [ { // cursor and node properties removed for brevity }, .... ] } } } } } ``` ## Retrieve the Next Batch After Using upperBound in a Subsequent Query 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 previous example, 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. ```sfdocs-code {"lang":"graphql", "title": "Query accounts using the upperBound argument in a subsequent query", "src": "" } { uiapi { query { Account(first:2000, after:"djE6MTk5OQ==", upperBound:5000) { totalCount pageInfo { hasPreviousPage hasNextPage startCursor endCursor } edges { cursor node { Id } } } } } } ``` The example result looks like this. ```sfdocs-code {"lang":"json", "title": "Subsequent upper-bound limit query result", "src": "" } { "data": { "uiapi": { "query": { "Account": { "totalCount": 4087, "pageInfo": { "hasPreviousPage": true, "hasNextPage": true, "startCursor": "djI6LTY1MTM3MjA4OjByOHh4MktEZkJBSTdJOUFXTC0yMDAw", "endCursor": "djI6LTY1MTM3MjA4OjByOHh4MktEZkJBSTdJOUFXTC0zOTk5" }, "edges": [ { "cursor": "djI6LTY1MTM3MjA4OjByOHh4MktEZkJBSTdJOUFXTC0yMDAw", "node": { "Id": "001xx000003GestAAC" } }, { "cursor": "djI6LTY1MTM3MjA4OjByOHh4MktEZkJBSTdJOUFXTC0yMDAx", "node": { "Id": "001xx000003GesuAAC" } }, ... ] } } } } } ``` Then you can make subsequent queries using `first` and `after` arguments to page through more results up to the upper-bound limit. ## Paging Through upperBound Child Relationships 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. ## Upper-Bound Pagination Limitations 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](/docs/platform/graphql/guide/paginate-use.md) without an upper-bound limit. - Records created after pagination begins aren't included in results. To view newly created records, refresh the results by restarting pagination from the beginning. - Paging through child relationships with large upper-bound limits can have performance implications. ## See Also [*SOAP API Developer Guide*: queryMore()](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_querymore.htm)