Paginating and filtering list endpoints
Guides & tutorials2 min read
Work with run artifacts, keys, webhooks, and portfolio lists safely.
Nexis exposes several list-shaped resources: run artifacts, API keys, webhooks and their deliveries, portfolio snapshots, wallet accounts. This guide covers the pattern for working with them. The exact cursor, limit, and filter parameters live in packages/schemas, not here, so confirm them there before you hardcode a query string.
Known list endpoints
| Endpoint | Returns | Notes |
|---|---|---|
| GET /v1/runs/{run_id}/artifacts | { artifacts } | Everything a run produced, scoped to that run |
| GET /v1/api-keys | API keys | Hashed, scoped, revocable |
| GET /v1/webhooks · /v1/webhook-deliveries | Webhooks and deliveries | Signed and retried |
| GET /v1/portfolio/snapshots | Portfolio snapshots | Read-only |
| GET /v1/wallets/accounts | Wallet accounts | Read |
Confirm parameters against the schema, not the client
packages/schemas is the source of truth for request, response, event, approval, and intent contracts. Do not duplicate or guess at public payload shapes in a client, pagination and filter parameters included; import the schema instead.
Cursor, limit, and filter names aren't enumerated here
The docs establish which endpoints return lists and what a list response envelope looks like. GET /v1/runs/{run_id}/artifacts, for example, resolves to { artifacts }. They do not publish the exact pagination or filter parameter names for every resource. Verify those against packages/schemas before you build a client against them.
General patterns once parameters are confirmed
- Prefer cursor-based iteration for resources that grow continuously while you might be reading, like webhook deliveries or run artifacts, over an offset that can skip or repeat rows under concurrent writes.
- Treat a filter as narrowing the same canonical resource state, not a separate view of it. The run ledger and portfolio snapshots are still the source of truth underneath any filtered read.
- Re-fetch rather than assume a listed page stays valid across a long-lived session, especially for refresh-driven reads like portfolio snapshots.
Was this page helpful?
Edit on GitHub