OpenAPIExtensions

Pagination

View as Markdown
Pro and Enterprise feature

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

The x-fern-pagination extension configures auto-pagination for list endpoints in your OpenAPI specification. Fern’s generated SDKs provide simple iterators that handle pagination automatically, so SDK users can loop through all results without managing pagination complexity 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'