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

# Read every page of a list

> Traverse management API lists with opaque cursors and consistent filters.

Every SDK `list()` call returns one page with `data` and `nextCursor`. A successful call does not necessarily return every matching resource.

Use pagination for environment cleanup, fixture selection, app discovery, and request inspection whenever the first page may be incomplete.

## Continue until the cursor is null

Process each page's `data`, then pass its `nextCursor` as the next call's `cursor`. Stop when `nextCursor` is `null`.

```ts theme={null}
import { StateMachines } from '@usestatemachines/sdk';

const sm = new StateMachines();
let cursor: string | undefined;

do {
  const page = await sm.environments.list({ cursor });

  for (const env of page.data) {
    console.log(env.id, env.name, env.status);
  }

  cursor = page.nextCursor ?? undefined;
} while (cursor !== undefined);
```

The example lists environments without changing them. The same loop applies to snapshots, apps, versions, workspaces, requests, and audit events, using the relevant method and required filters. [List filters](/sdk-api/client#list-filters) lists the filters each method accepts.

Treat cursors as opaque strings. Do not decode, edit, or construct them. Use the cursor returned by the immediately preceding page of the same query.

## Keep filters consistent

Carry the same filters into every call. For example, a request list must retain `environmentId`, and a filtered environment list must retain its status selection. The API binds cursors to the query scope. Changing filters while reusing a cursor can fail with `invalid_request` and a `fields.cursor` message. Start from the first page after changing filters.

Environment and snapshot lists leave deleted resources out unless the status filter asks for them. If a known environment is absent from the default list, read it by ID or explicitly include `deleted` before assuming it never existed.

## Choose a page size

`limit` defaults to 50 and accepts 1 to 100.

Process pages incrementally for larger result sets. If your next action is destructive, select the intended resource IDs before deleting anything. A broad list loop is not a safe substitute for identifying which environments belong to the task.

For versions and actors, match the environment's actual `versionId` after reading the relevant pages. Selecting the first version in the first page can choose a different version than the environment runs. See [credentials and actors](/environments/credentials).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.