Deep Dives

Configure Auto Pagination

Pro Feature

This feature is only available on paid plans. Please schedule a demo or email us to get started.

Fern’s auto pagination supports offset-based and cursor-based pagination schemes, providing SDK users with simple iterators to loop through all results instead of managing pagination complexity manually.

This page describes how to configure auto pagination for your API endpoints.

How it works for SDK users

Once you’ve configured pagination for an endpoint, Fern generates a TypeScript SDK method that returns a Page<T> where T is the underlying data type. The Page<T> will implement the AsyncIterable interface, allowing your users to use it in a for await loop.

Example generated method signature:

UsersClient.ts
1import core from "../core";
2
3export interface UsersClient {
4
5  /**
6   * List all users
7   * @param props 
8   * @returns A page of users
9   */
10  list(
11    request: ListUsersRequest = {}, 
12    requestOptions: core.RequestOptions = {}
13  ): core.Page<User>;
14}

Example of how users would call the list method:

1const response = await client.users.list();
2for await (const user of response) {
3  console.log(user);
4}

Setting up auto pagination

Setting up auto pagination involves defining your pagination scheme and where your results are located.

To set up auto pagination for OpenAPI:

  1. Annotate the desired paginated endpoint with the x-fern-pagination extension.
  2. Specify the pagination scheme, offset or cursor
  3. Specify where your results are located, using dot-access notation.
1...
2paths:
3  /path/to/my/endpoint:
4    x-fern-pagination: # Add pagination extension
5      offset: $request.page_number # Specify offset pagination scheme
6      results: $response.results # Specify result location
7...
How to find the location of your results

For example, if results of my_nested_object are located in the subfield inner_list, the dot-access path would be results: $response.my_nested_object.inner_list.

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

To set up auto pagination for the Fern Definition:

  1. Annotate the desired paginated endpoint with the pagination field.
  2. Specify the pagination scheme, offset or cursor
  3. Specify where your results are located, using dot-access notation.
1service:
2  endpoints:
3    listWithOffsetPagination:
4      pagination: # Add pagination field
5        offset: $request.page # Specify offset pagination scheme
6        results: $response.data # Specify result location