Runs API

Status and metadata for a workflow or custom node run.

Every workflow call and Studio test creates a run. Use its run_id to check what happened, for example after a timeout or when an idempotent retry returns 202.

GET /v1/runs/{run_id}

curl https://kovca.io/api/v1/runs/run_... \
  -H "Authorization: Bearer $KOVCA_API_KEY"

200 OK

{
  "request_id": "req_...",
  "run": {
    "id": "run_...",
    "request_id": "req_...",
    "kind": "workflow",
    "source": "api",
    "workflow": { "id": "wf_...", "version": 3 },
    "status": "succeeded",
    "started_at": "2026-10-29T18:58:35.917Z",
    "finished_at": "2026-10-29T18:58:37.204Z",
    "duration_ms": 1287,
    "evaluations": 2,
    "error": null,
    "steps": [
      { "id": "triage", "status": "succeeded", "reason": null, "evaluation": true, "duration_ms": 640 }
    ]
  }
}

Field	Type	Description
status	string	running, succeeded, failed, interrupted, or rejected (refused before anything ran, for example over quota).
evaluations	integer	Successful intelligence steps, which are billed whatever the run's final status.
error	object \| null	The error code and the step it came from.
steps	array	Steps Kovca recorded, with status, skip reason, whether it was an evaluation, and duration.

Interrupted runs

If a server stops mid-run, the run becomes interrupted within a few minutes. Steps that succeeded before that stay billed; nothing else runs. Kovca never resumes an interrupted run. Send the request again with a new idempotency key.

Retention

Runs are kept for 30 days, then return 404. Runs contain metadata only: Kovca never stores inputs or outputs, so keep the original response if you need the output.