> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Pagination

> Configure auto-pagination for list endpoints using the x-fern-pagination extension

The `x-fern-pagination` extension configures auto-pagination for list endpoints in your OpenAPI specification. [SDK](/learn/sdks/deep-dives/auto-pagination) and [CLI](/learn/cli-generator/get-started/openapi-extensions#pagination) users get automatic pagination without managing page tokens 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

**`Offset pagination`**

```yaml title="Offset pagination" {5-7}
paths:
  /plants:
    get:
      operationId: list_plants
      x-fern-pagination:
        offset: $request.page_number
        results: $response.results
      parameters:
        - name: page_number
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of plants
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plant'
```

**`Cursor pagination`**

```yaml title="Cursor pagination" {5-8}
paths:
  /plants:
    get:
      operationId: list_plants
      x-fern-pagination:
        cursor: $request.cursor
        next_cursor: $response.next
        results: $response.results
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of plants
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plant'
```

**`URI pagination`**

```yaml title="URI pagination" {5-7}
paths:
  /plants:
    get:
      operationId: list_plants
      x-fern-pagination:
        next_uri: $response.next_page_url
        results: $response.results
      responses:
        '200':
          description: List of plants
          content:
            application/json:
              schema:
                type: object
                properties:
                  next_page_url:
                    type: string
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plant'
```

**`Path pagination`**

```yaml title="Path pagination" {5-7}
paths:
  /plants:
    get:
      operationId: list_plants
      x-fern-pagination:
        next_path: $response.next_page_path
        results: $response.results
      responses:
        '200':
          description: List of plants
          content:
            application/json:
              schema:
                type: object
                properties:
                  next_page_path:
                    type: string
                    nullable: true
                  results:
                    type: array
                    items:
                      $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`.

```yaml {4, 7}
MyResponseObject:
  type: object
  properties:
    my_nested_object:
      type: object
      properties:
        inner_list:
          type: array
          items:
            $ref: '#/components/schemas/Plant'
```

> Configure auto-pagination for list endpoints using the x-fern-pagination extension