--- schema_version: "1" id: 12ddf05685b924843c20c936fb66a2158291c933337632dfc04b9664c90a4969 title: Paginate with Upper-Bound Limit collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/graphql-api/graphql/guides/paginate-use-upperbound.md canonical_url: https://developer.salesforce.com/docs/platform/graphql/guide/paginate-use-upperbound.html source_site: developer.salesforce.com content_type: documentation content_hash: b9fbe485be9874de586fcd235ef1c18b51ac07e3f94fddb62dc10ef2a7a78e34 products: - GraphQL API --- # 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. ``` query RecordsWithPagination { uiapi { query { Contact (first:200, upperBound:5000) { edges { node { Id Name { value } } } totalCount pageInfo { hasNextPage endCursor } } } } } ``` An example response looks like this. ``` { "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. ``` 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. ``` { 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. ``` { "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. ``` { 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. ``` { "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](https://developer.salesforce.com/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)