***

title: Pagination
headline: Pagination (OpenAPI)
description: >-
Configure auto-pagination for list endpoints using the x-fern-pagination
extension
---------

<Warning title="Pro and Enterprise feature">
  This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

The `x-fern-pagination` extension configures auto-pagination for list endpoints in your OpenAPI specification. [Fern's generated SDKs](/learn/sdks/deep-dives/auto-pagination) provide simple iterators that handle pagination automatically, so SDK users can loop through all results without managing pagination complexity manually.

To configure pagination, annotate the desired endpoint with the `x-fern-pagination` extension, specify the pagination scheme (`offset` or `cursor`), and indicate where your results are located using dot-access notation.

<CodeBlocks>
  ```yaml title="Offset pagination" {5-7}
  paths:
    /plants:
      get:
        operationId: list_plants
        x-fern-pagination:
          offset: $request.page_number
          results: $response.results
        parameters:
          - name: page_number
            in: query
            schema:
              type: integer
        responses:
          '200':
            description: List of plants
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Plant'
  ```

  ```yaml title="Cursor pagination" {5-8}
  paths:
    /plants:
      get:
        operationId: list_plants
        x-fern-pagination:
          cursor: $request.cursor
          next_cursor: $response.next
          results: $response.results
        parameters:
          - name: cursor
            in: query
            schema:
              type: string
        responses:
          '200':
            description: List of plants
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    next:
                      type: string
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Plant'
  ```
</CodeBlocks>

## Configuration options

The `x-fern-pagination` extension supports the following properties:

| Property        | Description                                                                    |
| --------------- | ------------------------------------------------------------------------------ |
| `offset`        | Path to the offset parameter in the request (e.g., `$request.page`)            |
| `cursor`        | Path to the cursor parameter in the request (e.g., `$request.cursor`)          |
| `next_cursor`   | Path to the next cursor value in the response (required for cursor pagination) |
| `results`       | Path to the results array in the response (e.g., `$response.data`)             |
| `step`          | Path to the page size parameter, ensures offset increments correctly           |
| `has-next-page` | Path to a boolean indicator for additional pages                               |

<Info title="Finding the location of your `results`">
  If your results are nested within the response object, use dot-access notation to specify the path. For example, if results are located in `my_nested_object.inner_list`, the `results` path would be `$response.my_nested_object.inner_list`.

  ```yaml {4, 7}
  MyResponseObject:
    type: object
    properties:
      my_nested_object:
        type: object
        properties:
          inner_list:
            type: array
            items:
              $ref: '#/components/schemas/Plant'
  ```
</Info>