# How to Use Pagination

Actions that return lists return them a page at a time.

## Page fields

| Field | Meaning |
|---|---|
| `page` | Page number, from 1. |
| `page_size` | Items per page; each action's range is on its tool page. |
| `has_more` | Whether another page follows. |
| `next_page` | The next page number; `null` on the last page. |

## The next page

Call the same action again with `page` set to `next_page`, until `next_page` is `null`. For example, the second page of the `list` action of [Companies](/documents/companies.md):

```json title="MCP"
{"action": "list", "jurisdiction": "US", "page": 2}
```

```bash title="CLI"
akkru companies list --jurisdiction US --page 2
```

## Several pages in one CLI run

`--pages N` fetches up to N pages in one run, from `--page` (default 1); without `--yes` only the first page is fetched. The pages come back as a list in `data`, with `next_page`.

```bash title="CLI"
akkru companies list --jurisdiction US --page-size 5 --pages 3 --yes
```

> [!WARNING]
> Each page is a separate call and is charged. The `search` actions that screen across companies return only their first 500 rows: `page` × `page_size` can be at most 500. Narrow the filters to reach the others.