> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/zenlayer-cli/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/zenlayer-cli/usage/pagination.md).

# Pagination

Many list commands (e.g., `describe-instances`, `describe-eips`) return large result sets split across multiple pages. Zenlayer Cloud CLI gives you two ways to work with paginated APIs: **manual pagination** using `--page-num` / `--page-size`, or **automatic pagination** using `--page-all`.

## Manual Pagination

Use `--page-num` and `--page-size` to request a specific page of results.

| Flag          | Type    | Default | Description                              |
| ------------- | ------- | ------- | ---------------------------------------- |
| `--page-num`  | integer | 1       | Page number to retrieve.                 |
| `--page-size` | integer | 20      | Number of items per page. Maximum: 1000. |

```bash
# Get the first page with 20 items (API default)
zeno zec describe-instances

# Get the second page with 50 items per page
zeno zec describe-instances --page-num 2 --page-size 50
```

The response includes a `totalCount` field that tells you the total number of matching items, so you can calculate how many pages exist:

```json
{
  "totalCount": 135,
  "instanceSet": [ ... ]
}
```

## Automatic Pagination (`--page-all`)

When you add `--page-all`, the CLI automatically fetches every page and merges the results into a single response. You no longer need to loop manually.

```bash
# Fetch all instances in one command
zeno zec describe-instances --page-all

# Combine with filters
zeno zec describe-instances --page-all --status RUNNING

# Control the batch size (items fetched per API request)
zeno zec describe-instances --page-all --page-size 100
```

### How It Works

1. Starts from page 1, regardless of any `--page-num` value.
2. Uses `--page-size` as the batch size per request (defaults to **100** if not set).
3. Repeats until one of these stop conditions is met:
   * The accumulated item count reaches `totalCount`.
   * A page returns fewer items than the requested page size (signals the last page).
4. Returns a single merged response where the data array contains all items. Metadata fields (`totalCount`, `requestId`) are taken from the first page.

### Example Output

```json
{
  "totalCount": 135,
  "instanceSet": [
    { "instanceId": "ins-001", "status": "RUNNING" },
    { "instanceId": "ins-002", "status": "STOPPED" },
    ...
  ],
  "requestId": "abc-123"
}
```

`--page-all` is only available on commands that support pagination. It does not appear on non-paginated commands.

## Combining with Other Flags

`--page-all` composes naturally with output and query flags:

```bash
# Get all instances and output as a table
zeno zec describe-instances --page-all --output table

# Get all instance IDs using a JMESPath query
zeno zec describe-instances --page-all --query "instanceSet[*].instanceId"

# Save all results to a file
zeno zec describe-instances --page-all --output json > all-instances.json
```

## Related Documentation

* [Output Formats](/zenlayer-cli/usage/output.md) — Learn about JSON and table output formats
* [Parameter Types](/zenlayer-cli/usage/parameter-types.md) — Learn about different parameter type usage


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.console.zenlayer.com/zenlayer-cli/usage/pagination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.