{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/products/payments-direct-2/api-docs/developer-guides/paginate-through-results","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/v2026.03/api-docs/developer-guides/paginate-through-results","default":false,"active":false,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/developer-guides/paginate-through-results","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Paginate through results","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"paginate-through-results","__idx":0},"children":["Paginate through results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Several ","Payments Direct"," API endpoints return paginated results when a list could contain many records. The API uses two pagination styles depending on the endpoint:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Token-based pagination"]}," for identities, financial instruments, and payment search. The response includes an opaque ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]}," value that you pass to retrieve the next page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Offset-based pagination"]}," for ledger transactions. You specify a starting record index (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]},") and the number of records to return (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The table below summarizes which style applies to each paginated endpoint."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Style"},"children":["Style"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Page size parameter"},"children":["Page size parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Maximum"},"children":["Maximum"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token-based"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["100"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}/financial-instruments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token-based"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["100"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/payments/filter"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token-based (request body)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page.size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["20"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["100"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/ledger-transactions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Offset-based"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["25"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["50"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"token-based-pagination","__idx":1},"children":["Token-based pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token-based pagination uses an opaque string token to mark your position in a result set. When the API returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]}," in the response, more results are available. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]}," is absent, you have reached the last page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens are opaque and may change between releases. Do not attempt to decode, parse, or construct token values."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identities-and-financial-instruments","__idx":2},"children":["Identities and financial instruments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}/financial-instruments"]},", pass pagination parameters as query parameters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request parameters:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maximum number of records to return. Default is 10, maximum is 100."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Opaque token returned by the previous response. Omit this parameter to start from the beginning."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: First page"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities?limit=25\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response (more pages available):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    { \"identityId\": \"abc123\", \"identityType\": \"INDIVIDUAL\", \"...\" },\n    { \"...\" }\n  ],\n  \"nextToken\": \"eyJrZXkxIjoidmFsdWUifQ==\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Subsequent page"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities?limit=25&next-token=eyJrZXkxIjoidmFsdWUifQ==\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the response does not include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]}," field, you have retrieved all available records."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-search","__idx":3},"children":["Payment search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/payments/filter"]}," endpoint uses token-based pagination, but the pagination parameters are passed in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["request body"]}," rather than as query parameters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body pagination fields:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page.size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of payments to return per page. Default is 20, maximum is 100."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page.lastPageToken"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token returned in the previous response. Omit to retrieve the first page."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: First page"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/payments/filter\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filter\": {\n      \"paymentStates\": [\"COMPLETED\"]\n    },\n    \"sort\": {\n      \"sortField\": \"CREATED_AT\",\n      \"sortDirection\": \"DESC\"\n    },\n    \"page\": {\n      \"size\": 20\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response (more pages available):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [ { \"...\" } ],\n  \"filter\": { \"...\" },\n  \"sort\": { \"...\" },\n  \"page\": {\n    \"size\": 20,\n    \"lastPageToken\": \"eyJsYXN0SWQiOiJhYmMxMjMifQ==\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Subsequent page"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastPageToken"]}," value from the previous response in the next request body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"page\": {\n    \"size\": 20,\n    \"lastPageToken\": \"eyJsYXN0SWQiOiJhYmMxMjMifQ==\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the response does not include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page.lastPageToken"]}," field, you have retrieved all matching payments."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"offset-based-pagination","__idx":4},"children":["Offset-based pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/ledger-transactions"]}," endpoint uses offset-based pagination. You control the result window with two parameters: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}," (how many records to return) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," (how many records to skip)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request parameters:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of records to return. Default is 25, maximum is 50."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of records to skip before returning results. Default is 0 (start from the beginning)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," field with the overall count of matching records. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageElements"]}," to determine whether additional pages exist."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response fields:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total number of records matching the request filters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of records requested per page (echoes the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}," parameter)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageElements"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of records actually returned in this response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of records skipped (echoes the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," parameter)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: First page"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"offset\": 0,\n  \"pageSize\": 25,\n  \"pageElements\": 25,\n  \"total\": 83,\n  \"statementTransactions\": [ { \"...\" } ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Second page"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total=83"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize=25"]},", the second page starts at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset=25"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25&offset=25\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You have retrieved all records when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset + pageElements >= total"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":5},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use the maximum page size for bulk retrieval."]}," When your goal is to retrieve all records (for example, for reconciliation), set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}," to the maximum allowed value to minimize the number of requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check for the absence of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]},", not its value."]}," For token-based endpoints, the correct signal that you have reached the last page is the absence of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page.lastPageToken"]},") in the response, not a specific token value."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not modify or construct tokens."]}," Tokens are opaque. Building logic that parses or concatenates token values will break when the token format changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account for records added during retrieval."]}," Offset-based pagination over an actively changing result set can produce gaps or duplicates. For ledger transactions, use a fixed time range (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start-dttm"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end-dttm"]},") to ensure the result set does not change while you paginate through it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not cache tokens across sessions."]}," Tokens are only valid for the session in which they were issued. Always start a fresh pagination sequence for a new retrieval job."]}]},"headings":[{"value":"Paginate through results","id":"paginate-through-results","depth":1},{"value":"Token-based pagination","id":"token-based-pagination","depth":2},{"value":"Identities and financial instruments","id":"identities-and-financial-instruments","depth":3},{"value":"Payment search","id":"payment-search","depth":3},{"value":"Offset-based pagination","id":"offset-based-pagination","depth":2},{"value":"Best practices","id":"best-practices","depth":2}],"frontmatter":{"seo":{"title":"Paginate through results"}},"lastModified":"2026-05-27T18:08:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/developer-guides/paginate-through-results","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}