List Workflow Runs

List recorded runs of a workflow with filtering and opaque cursor pagination. Ordering deviates from the v2 sortBy + sortOrder convention: runs are sortable only by start time, so direction is carried by the single order param.

GET/api/v2/workflows/{id}/runs

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as 403 unless the operation conceals unauthorized resources, in which case it is reported as 404. Use a personal API key for those.

In: header

Path Parameters

id*string

Unique workflow identifier.

Length1 <= length

Query Parameters

status?string

Filter by run status.

Value in"pending" | "running" | "completed" | "failed" | "cancelled" | "paused"
trigger?string

Filter by trigger type.

Length1 <= length
startDate?string

Include runs started at or after this ISO 8601 timestamp.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Formatdate-time
endDate?string

Include runs started at or before this ISO 8601 timestamp.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Formatdate-time
limit?integer

Maximum workflow runs to return per page.

Default50
Range1 <= value <= 100
cursor?string

Opaque pagination cursor returned by a previous request.

Length1 <= length
order?string

Sort direction by run start time. This operation deviates from the v2 sortBy + sortOrder convention: runs are sortable only by start time, so the direction is carried by this single order param and sortBy/sortOrder are not accepted.

Default"desc"
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs"
{
  "data": [
    {
      "runId": "run_8f14e45f-ceea-467f-a",
      "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
      "status": "completed",
      "trigger": "api",
      "startedAt": "2026-08-09T18:04:10.000Z",
      "endedAt": "2026-08-09T18:04:11.000Z",
      "durationMs": 1000,
      "cost": {
        "total": 12
      }
    }
  ],
  "nextCursor": null
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}