Pagination

The x-fern-pagination extension configures auto-pagination for list endpoints in your OpenAPI specification. SDK and CLI users get automatic pagination without managing page tokens manually.

To configure pagination:

Annotate the desired paginated endpoint with the x-fern-pagination extension
Specify the pagination scheme (offset, cursor, next_uri, or next_path)
Specify where your results are located using dot-access notation

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'

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)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`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

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.

MyResponseObject:
  type: object
  properties:
    my_nested_object:
      type: object
      properties:
        inner_list:
          type: array
          items:
            $ref: '#/components/schemas/Plant'