List runs

GET

/v1/runs

GET

/v1/runs

curl https://api.runtype.com/v1/runs \
     -H "Authorization: <apiKey>"

{
  "data": [
    {
      "agentId": "string",
      "batchExecutionId": "string",
      "completeness": "partial",
      "conversationId": "string",
      "durationMs": 1.1,
      "endedAt": "string",
      "executionId": "string",
      "fidelityTier": "string",
      "flowId": "string",
      "inputTokens": 1.1,
      "kind": "agent",
      "outputTokens": 1.1,
      "parentExecutionId": "string",
      "parentToolCallId": "string",
      "recordId": "string",
      "rootExecutionId": "string",
      "selfReportedCost": "string",
      "source": "hosted",
      "spanCount": 1.1,
      "startedAt": "string",
      "status": "queued",
      "surfaceId": "string",
      "surfaceType": "string",
      "test": true,
      "totalCost": "string",
      "traceId": "string",
      "agentTargetResolution": "string",
      "agentVersionId": "string",
      "agentVersionLabel": "string",
      "agentVersionNumber": 1.1,
      "budgetExhausted": true,
      "cancelRequestedAt": "string",
      "expiresAt": "string",
      "inputMessages": null,
      "iterations": 1.1,
      "lastHeartbeatAt": "string",
      "otelProducer": null,
      "pendingApproval": null,
      "progress": null,
      "retentionElided": true,
      "stopReason": "string"
    }
  ],
  "pagination": {
    "hasMore": true,
    "hasPrev": true,
    "limit": 1,
    "nextCursor": "string"
  },
  "window": {
    "from": "string",
    "to": "string"
  }
}

Every agent and flow run in the span store, newest start first. A run dispatched with storeResults: false is listed with test: true rather than being invisible. overlay=live adds live control-plane fields; the overlay never adds, drops or reorders a row. Returns 404 when run reads are not enabled for the organization.

Authentication

AuthorizationBearer

API key or Clerk session token

Query parameters

agentIdstring or list of stringsOptional

Filter by agent id; repeat for a set.

flowIdstring or list of stringsOptional

Filter by flow id; repeat for a set.

conversationIdstringOptional

Filter by conversation id.

surfaceIdstringOptional

Filter by surface id.

surfaceTypestringOptional

Filter by surface family.

recordIdstringOptional

Filter by record id.

batchExecutionIdstring or list of stringsOptional

Filter by batch id; repeat for a set.

parentExecutionIdstringOptional

Runs spawned by this execution.

rootExecutionIdstringOptional

Runs in this execution tree.

executionIdstring or list of stringsOptional

Read specific runs by id; at most 100 per request.

sourceenumOptional

Filter by producing lane.

Allowed values:

statusenumOptional

status accepts only running, completed or failed. queued, awaiting and cancelled exist only in the live overlay, which may never change which rows a page holds, so the server cannot filter on them.

Allowed values:

fromstringOptional

Window start (ISO 8601). Defaults to 24 hours ago.

tostringOptional

Window end (ISO 8601). Defaults to now.

viewenumOptional

full (the default) returns every field. compact omits exactly these 14: stopReason, iterations, agentVersionId, agentVersionLabel, agentVersionNumber, agentTargetResolution, otelProducer, lastHeartbeatAt, expiresAt, cancelRequestedAt, progress, pendingApproval, budgetExhausted and inputMessages. The status is still overlay-corrected on a compact page; only the fields differ.

Allowed values:

overlayenumOptional

live adds control-plane fields; defaults to live for a session, none for an API key.

Allowed values:

limitstringOptional

Page size, at most 100.

cursorstringOptional

Keyset cursor from a previous page.

Response

Runs returned

datalist of objects

paginationobject

windowobject

The started_at window the query resolved to, after defaults.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error