Auto Pagination

Pro Feature

This feature is only available on paid plans. Contact us to get started.

Instead of forcing SDK users to learn the intricacies of your pagination system, Fern SDKs will return an iterator so that users can simply loop through all the results.

When pagination for an endpoint is configured, the TypeScript SDK method will return a Page<T> where T is the underlying data type. The Page<T> will implement the AsyncIterable interface, allowing you to use it in a for await loop.

Below is an example method signature for a list endpoint:

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}

And here is an example of how a user would use the list method:

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

Supported pagination types

Fern supports the following pagination schemes:

Pagination SchemeSupported
Offset-based
Cursor-based
Link-based

Configuration

Annotate the desired paginated endpoint with the x-fern-pagination extension. For these fields, you can simply specify the dot-access path to the related request or response property.

For example, should the results of the following object be found in the subfield inner_list, you would specify 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:
8          type: array
9          items:
10            $ref: '#/components/schemas/MyObject'
1...
2paths:
3  /path/to/my/endpoint:
4    x-fern-pagination:
5      offset: $request.page_number
6      results: $response.results
7...