Read every page of a list - State Machines

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.

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 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.

​Continue until the cursor is null

​Keep filters consistent

​Choose a page size

Continue until the cursor is null

Keep filters consistent

Choose a page size