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

TypeScript

Python

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

1 import core from "../core";
2 
3 export 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:

1 const response = await client.users.list();
2 for 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.

OpenAPI

To set up auto pagination for OpenAPI:

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

1 ...
2 paths:
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.

1 MyResponseObject:
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'

Fern Definition

To set up auto pagination for the Fern Definition:

Annotate the desired paginated endpoint with the pagination field.
Specify the pagination scheme, offset or cursor
Specify where your results are located, using dot-access notation.

1 service:
2   endpoints:
3     listWithOffsetPagination:
4       pagination: # Add pagination field
5         offset: $request.page # Specify offset pagination scheme
6         results: $response.data # Specify result location

Pro Feature

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

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

How it works for SDK users

TypeScript

Python

Example generated method signature:

UsersClient.ts

1 import core from "../core";
2 
3 export 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:

1 const response = await client.users.list();
2 for 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.

OpenAPI

To set up auto pagination for OpenAPI:

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

1 ...
2 paths:
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.

1 MyResponseObject:
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'

Fern Definition

To set up auto pagination for the Fern Definition:

Annotate the desired paginated endpoint with the pagination field.
Specify the pagination scheme, offset or cursor
Specify where your results are located, using dot-access notation.

1 service:
2   endpoints:
3     listWithOffsetPagination:
4       pagination: # Add pagination field
5         offset: $request.page # Specify offset pagination scheme
6         results: $response.data # Specify result location

1	import core from "../core";
2
3	export 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	}

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

1	...
2	paths:
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	...

1	MyResponseObject:
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'

1	service:
2	endpoints:
3	listWithOffsetPagination:
4	pagination: # Add pagination field
5	offset: $request.page # Specify offset pagination scheme
6	results: $response.data # Specify result location