Pagination

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:

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

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

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path 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.

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

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:

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

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

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path to a boolean indicator for additional pages

Finding the location of your `results`

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

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

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

Enterprise feature

Configuration options

Finding the location of your results

Enterprise feature

Configuration options

Finding the location of your results

Finding the location of your `results`

Finding the location of your `results`