Deployments.ai Docs
Runtime

List agent runs in the environment, optionally for one deployment or binding

GET /v1/runs · SDK listRuns · CLI deployments run list

GET
/v1/runs

Requires runs:read.

Authorization

headerAuthorizationBearer <token>

Opaque bearer credential scoped to one service account and tenant.

Query Parameters

cursor?string

Opaque cursor returned by the previous page.

Length1 <= length <= 4096
limit?integer

Maximum number of resources to return.

Range1 <= value <= 100
agentDeploymentId?string

Agent deployment whose runs should be returned. At most one of agentDeploymentId and executionBindingId may be set; with neither, every run in the environment is returned newest first.

executionBindingId?string

Preview or evaluation execution binding whose runs should be returned. At most one of agentDeploymentId and executionBindingId may be set.

agentReleaseId?string

Only return runs pinned to this agent release.

status?string

Only return runs in this status.

Value in"canceled""completed""failed""queued""running""waiting-for-approval""waiting-for-tool"
executionPurpose?string

Only return runs executed for this purpose.

Value in"customer""evaluation""preview"
threadId?string

Only return runs of this thread.

createdAfter?string

Only return runs created at or after this canonical UTC millisecond timestamp.

Formatdate-time
createdBefore?string

Only return runs created at or before this canonical UTC millisecond timestamp.

Formatdate-time

Header Parameters

x-deployments-environment?string

Required with a platform bearer JWT, where the three tenant headers select an environment the caller can access through active organization membership. Optional with an API key; when supplied, it must match the key's tenant.

Match^[0-7][0-9A-HJKMNP-TV-Z]{25}$
x-deployments-organization?string

Required with a platform bearer JWT, where the three tenant headers select an environment the caller can access through active organization membership. Optional with an API key; when supplied, it must match the key's tenant.

Match^[0-7][0-9A-HJKMNP-TV-Z]{25}$
x-deployments-project?string

Required with a platform bearer JWT, where the three tenant headers select an environment the caller can access through active organization membership. Optional with an API key; when supplied, it must match the key's tenant.

Match^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Response Body

ListRunsResponse

application/json
  1. response
nextCursor?|null
runs*array<>
curl -X GET "https://example.com/v1/runs"
{  "nextCursor": "string",  "runs": [    {      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "version": 0,      "environmentId": "string",      "organizationId": "string",      "projectId": "string",      "workspaceId": "string",      "agentDeploymentId": "string",      "agentReleaseId": "string",      "attempt": 0,      "automation": {        "fireId": "string",        "id": "string",        "kind": "heartbeat"      },      "checkpointCount": 0,      "completedAt": "2019-08-24T14:15:22Z",      "error": {        "property1": null,        "property2": null      },      "executionBindingId": "string",      "executionPurpose": "customer",      "executor": "string",      "id": "string",      "object": "run",      "parentSpanId": "string",      "priority": 0,      "releaseSelection": "candidate",      "replayedFromRunId": "string",      "replayedFromTraceId": "string",      "spanId": "string",      "startedAt": "2019-08-24T14:15:22Z",      "status": "canceled",      "threadId": "string",      "traceId": "string",      "trigger": "string"    }  ]}