Deployments.ai Docs
Runtime

Search agent runs

POST /v1/runs/search · SDK searchRuns · CLI deployments run search

POST
/v1/runs/search

Requires runs:read. A suspended organization can still call it.

Authorization

headerAuthorizationBearer <token>

Opaque bearer credential scoped to one service account and tenant.

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}$

Request Body

application/json
  1. body
agentDeploymentId?string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
agentReleaseId?string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
createdAfter?string
Match^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
Formatdate-time
createdBefore?string
Match^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
Formatdate-time
cursor?string
Length1 <= length <= 4096
executionBindingId?string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
executionPurpose?string
Value in"customer""evaluation""preview"
limit?integer
Range1 <= value <= 100
status?string
Value in"canceled""completed""failed""queued""running""waiting-for-approval""waiting-for-tool"
threadId?string
Match^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$

Response Body

ListRunsResponse

application/json
  1. response
nextCursor?|null
runs*array<>
curl -X POST "https://example.com/v1/runs/search" \  -H "Content-Type: application/json" \  -d '{}'
{  "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"    }  ]}