# Source: https://gofastmcp.com/python-sdk/fastmcp-utilities-pagination.md

> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# pagination

# `fastmcp.utilities.pagination`

Pagination utilities for MCP list operations.

## Functions

### `paginate_sequence` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
paginate_sequence(items: Sequence[T], cursor: str | None, page_size: int) -> tuple[list[T], str | None]
```

Paginate a sequence of items.

**Args:**

* `items`: The full sequence to paginate.
* `cursor`: Optional cursor from a previous request. None for first page.
* `page_size`: Maximum number of items per page.

**Returns:**

* Tuple of (page\_items, next\_cursor). next\_cursor is None if no more pages.

**Raises:**

* `ValueError`: If the cursor is invalid.

## Classes

### `CursorState` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Internal representation of pagination cursor state.

The cursor encodes the offset into the result set. This is opaque to clients
per the MCP spec - they should not parse or modify cursors.

**Methods:**

#### `encode` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
encode(self) -> str
```

Encode cursor state to an opaque string.

#### `decode` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
decode(cls, cursor: str) -> CursorState
```

Decode cursor from an opaque string.

**Raises:**

* `ValueError`: If the cursor is invalid or malformed.