# Configure auto pagination

> Paginate through API responses easily with offset, cursor, and link-based pagination.

<Warning title="Pro and Enterprise feature">
  This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

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

<Tabs>
  <Tab title="TypeScript" language="typescript">
    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:

    ```typescript UsersClient.ts {10-13}
    import core from "../core";

    export interface UsersClient {

      /**
       * List all users
       * @param props 
       * @returns A page of users
       */
      list(
        request: ListUsersRequest = {}, 
        requestOptions: core.RequestOptions = {}
      ): core.Page<User>;
    }
    ```

    Example of how users would call the `list` method:

    ```typescript
    const response = await client.users.list();
    for await (const user of response) {
      console.log(user);
    }
    ```
  </Tab>

  <Tab title="Python" language="python">
    Once you've configured pagination for an endpoint, Fern generates a Python SDK
    method that returns a `Pager[T]` where `T` is the underlying data type. The
    `Pager[T]` will implement the `Generator` interface, allowing your users to
    use it in a `for ... in` loop.

    Example generated method signature:

    ```python client.py {3-9}
    class UsersClient:

      def list_with_cursor_pagination(
          self,
          *,
          page: typing.Optional[int] = None,
          page_size: typing.Optional[int] = None,
          request_options: typing.Optional[RequestOptions] = None,
      ) -> SyncPager[User]:
        ...
    ```

    Example of how users would call the `list` method:

    ```python
    for user in client.users.list(page=1, page_size=10):
      print(user)
    ```

    or if the user is leveraging the asynchronous client:

    ```python
    async for user in await client.users.list(page=1, page_size=10):
      print(user)
    ```
  </Tab>
</Tabs>

## Setting up auto pagination

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

<AccordionGroup>
  <Accordion title="OpenAPI">
    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.

    <CodeBlocks>
      ```yaml Offset {4-6}
      ...
      paths:
        /path/to/my/endpoint:
          x-fern-pagination: # Add pagination extension
            offset: $request.page_number # Specify offset pagination scheme
            results: $response.results # Specify result location
      ...
      ```

      ```yaml Cursor {5-8}
      ...
      paths:
        /path/to/my/endpoint:
          get:
            x-fern-pagination: # Add pagination extension
              cursor: $request.cursor # Specify cursor pagination scheme
              next_cursor: $response.next
              results: $response.results # Specify result location
      ...
      ```
    </CodeBlocks>

    <Info title="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`.

      ```yaml {4, 7}
      MyResponseObject:
        type: object
        properties:
          my_nested_object:
            type: object
            properties:
              inner_list: # location of results
                type: array
                items:
                  $ref: '#/components/schemas/MyObject'
      ```
    </Info>
  </Accordion>

  <Accordion title="Fern Definition">
    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.

    <Tip title="Offset pagination options">
      Include `step` in most offset pagination configurations to ensure the offset increments by the page size. Use `has-next-page` when your API returns a boolean indicator for additional pages.
    </Tip>

    <CodeBlocks>
      ```yaml Offset {6-8}
      service:
        endpoints:
          listWithOffsetPagination:
            pagination: # Add pagination field
              offset: $request.page # Specify offset pagination scheme
              results: $response.data # Specify result location
              step: $request.page_size # Recommended: ensures offset increments correctly
              has-next-page: $response.has_more # Optional: path to next page indicator
      ```

      ```yaml Cursor {7}
      service:
        endpoints:
          listWithCursorPagination:
            pagination: # Add pagination field
              cursor: $request.starting_after # Specify cursor pagination scheme
              next_cursor: $response.page.next.starting_after
              results: $response.data # Specify result location
      ```
    </CodeBlocks>
  </Accordion>
</AccordionGroup>