Pagination and filtering

Pagination

Every list method takes page_size, page_token, filter and order_by, and returns items and next_page_token.

# first page
curl -sS $BASE/slipway.v1.RunService/ListRuns -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  -d '{"project_id":"proj_01H...","page_size":100}'
# next page: pass next_page_token back unchanged
curl -sS $BASE/slipway.v1.RunService/ListRuns -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  -d '{"project_id":"proj_01H...","page_size":100,"page_token":"eyJ..."}'

• Default page size 50, maximum 500.
• Tokens are opaque: base64 of the sort key and id. Do not parse or construct them.
• An empty next_page_token means the last page.
• Tokens are stable under concurrent inserts for the same order_by.

let token = "";
do {
  const page = await runs.listRuns({ projectId, pageSize: 200, pageToken: token });
  handle(page.items);
  token = page.nextPageToken;
} while (token);

Filtering

filter accepts a tiny subset of CEL: comparisons joined with &&. The fields available are documented per endpoint.

status == "failed" && branch == "main"
environment == "production" && status in ["succeeded", "rolled_back"]
name.startsWith("api-")

Supported	Examples
Equality and inequality	==, !=
Comparison	<, <=, >, >= (numbers and timestamps)
Membership	status in ["failed", "errored"]
String methods	startsWith, endsWith, contains
Combine	&& (and), `

An invalid filter returns invalid_argument with a field violation on filter naming the problem.

Ordering

order_by takes a field name with an optional desc suffix, for example created_at desc. Each endpoint lists its sortable fields; the default is newest first for time-ordered resources.

CLI

The CLI exposes the same paging through --limit and the most useful filters as flags (--status, --branch, --env, --service), and --json for machine output.