> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

xPay API utilizes [cursor](http://en.wikipedia.org/wiki/Cursor_\(databases\)) based pagination to efficiently handle large datasets. All list API methods share a common structure and accept pagination parameters to facilitate navigation through results.

## Understanding Cursor-Based Pagination

Cursor based pagination utilizes a special token (called an `offset`) that functions as a bookmark, instructing the API precisely where to resume fetching data from. This approach is efficient for large datasets because it eliminates the necessity for the API to count total results.

## Implementation Steps

1. **Initial request**: Omit `offset` parameter
2. **Continue**: For each subsequent request, supply the exact `offset` value received in the previous response's `metadata.offset` field. Do not alter, generate, or reuse old offsets.
3. **Complete**: Terminate when `metadata.offset` is absent or null

<Note>
  **Modifying query parameters**: Changing any query parameters (such as filters or sorting) invalidates current offsets, restart pagination from the beginning if you change them.
</Note>

<Info>
  **Too many requests**: Excessive paginated requests within a short period may result in [rate limiting](/developer-resources/rate-limits).
</Info>

## Parameters

<ParamField path="limit" type="number">
  Specifies the number of objects to return, ranging between 1 and 100. Default varies by endpoint.
</ParamField>

<ParamField path="offset" type="string">
  An opaque string that defines your position in the list.

  <Warning>
    **Critical**: Utilize the exact `offset` value from the previous response's `metadata.offset` field. Do not modify, decode, or generate your own offset values.
  </Warning>
</ParamField>

## Response Format

All paginated endpoints return responses in this format:

<ResponseField name="data" type="array" required>
  Array of response elements containing the actual data objects
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Metadata object containing pagination information

  <Expandable title="child attributes " defaultOpen>
    <ResponseField name="metadata.offset" type="string">
      Cursor for the next page. When absent or null, you've reached the conclusion
    </ResponseField>
  </Expandable>
</ResponseField>