OpenAPIExtensions

Pagination

View as Markdown
Enterprise feature

This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.

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:

  1. Annotate the desired paginated endpoint with the x-fern-pagination extension
  2. Specify the pagination scheme (offset, cursor, next_uri, or next_path)
  3. Specify where your results are located using dot-access notation
1paths:
2  /plants:
3    get:
4      operationId: list_plants
5      x-fern-pagination:
6        offset: $request.page_number
7        results: $response.results
8      parameters:
9        - name: page_number
10          in: query
11          schema:
12            type: integer
13      responses:
14        '200':
15          description: List of plants
16          content:
17            application/json:
18              schema:
19                type: object
20                properties:
21                  results:
22                    type: array
23                    items:
24                      $ref: '#/components/schemas/Plant'

Configuration options

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

PropertyDescription
offsetPath to the offset parameter in the request (e.g., $request.page)
cursorPath to the cursor parameter in the request (e.g., $request.cursor)
next_cursorPath to the next cursor value in the response (required for cursor pagination)
next_uriPath to the next page’s URL in the response (e.g., $response.next_page_url)
next_pathPath to the relative path for the next page in the response (e.g., $response.next_page_path)
resultsPath to the results array in the response (e.g., $response.data)
stepPath to the page size parameter, ensures offset increments correctly
has-next-pagePath 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.

1MyResponseObject:
2  type: object
3  properties:
4    my_nested_object:
5      type: object
6      properties:
7        inner_list:
8          type: array
9          items:
10            $ref: '#/components/schemas/Plant'