Skip to main content

Runs and approvals

A run is identified by its workflow_id, such as agent-run-3f9a1c2e. These endpoints need a Keycloak access token. See Authentication.

Runs that belong to a project are authorized against that project. A run with no project, such as a model build, needs the admin platform role.

List recent runs​

GET/workflows/runs

The most recent runs you can see, newest first. Orchestrate reads the 20 most recent runs on the platform and returns the ones in projects you have a role on, so you can get fewer than 20. Runs with no project, such as model builds and document ingestion, are returned to platform admins only. For running agent runs it also says which step they are on and whether they wait for approval.

Response fields​

runs[].idstringoptional
The workflow_id.
runs[].workflow_typestringoptional
For example AgentRunWorkflow, BuildModelImageWorkflow, DeployModelWorkflow, IngestDocumentWorkflow, EvalRunWorkflow or ExecuteToolWorkflow.
runs[].statusstringoptional
RUNNING, COMPLETED, FAILED, CANCELED, TERMINATED or TIMED_OUT.
runs[].project_idstring or nulloptional
The project the run belongs to.
runs[].start_timestringoptional
When it started.
runs[].close_timestring or nulloptional
When it ended.
runs[].pending_approvalsarrayoptional
Open approval requests, for a running agent run.
runs[].progressobject or nulloptional
Each step's name and status, and what the run is doing now, for a running agent run.

Get a run​

GET/workflow-runs/{workflow_id}

One run's status, live progress, approvals and, if it failed, why. Works while the run is going and after it ends. Needs any role on the run's project.

Response fields​

statusstringoptional
The run's status, as in the list.
progressobject or nulloptional
For an agent run: input, started_by, steps and current. null for other run types.
progress.steps[]objectoptional
Each step's name, model, tools, status (pending, running, done, failed or canceled), started_at, finished_at, model_calls, tool_calls, output and error.
progress.currentobject or nulloptional
What the run is waiting on now: kind is model_call, approval_check, awaiting_approval or tool_call, with the step and when it started.
pending_approvalsarrayoptional
Approval requests still open.
resolved_approvalsarrayoptional
Approval requests already decided.
failureobject or nulloptional
For a run that did not complete: type, message, non_retryable and detail. A rejected approval has type ApprovalRejected.

Responses​

200
The run.
403
You have no role on the run's project.
404
No such run.

List a run's approvals​

GET/workflow-runs/{workflow_id}/approvals

What the run is waiting for, and what it has already been told. Needs any role on the run's project.

Response fields​

pendingarrayoptional
Open requests.
pending[].approval_idstringoptional
The request's id, for the decision call.
pending[].stepstringoptional
The step that wants to call the tool.
pending[].tool_namestringoptional
The tool.
pending[].argumentsobjectoptional
The exact arguments the call would use.
pending[].reason_gatedstringoptional
policy when policy required approval, always when the step requires it for every call.
pending[].requested_bystringoptional
Who started the run.
pending[].requested_atstringoptional
When the call stopped.
pending[].expires_atstringoptional
When it is rejected if nobody decides.
resolvedarrayoptional
Decided requests, with decision (approve or reject), actor, reason, timed_out and decided_at.
statusstringoptional
The run's status.

Decide an approval​

POST/workflow-runs/{workflow_id}/approvals/{approval_id}

Approves or rejects one open request. The call returns only after the run has acted on the decision. Needs the developer or admin role on the run's project.

Body​

decisionstringrequired
approve or reject.
reasonstringoptional
Why. Recorded in the audit log.

Response fields​

workflow_idstringoptional
The run.
approvalobjectoptional
The decided request, as the run recorded it.

Responses​

200
The run acted on the decision.
400
decision is not approve or reject.
403
You are not a developer or admin on the run's project.
404
No such run.
409
The request is not open. It was already decided, or it expired. detail says which, and by whom.

Cancel a run​

POST/workflow-runs/{workflow_id}/cancel

Stops a run that is still going, for example a workflow waiting at an approval gate or a loop you no longer need. Needs the developer or admin role on the run's project. The cancel is audited. A run cancelled while the API was waiting for it answers with status canceled.

Responses​

202
Cancel requested.
404
No such run, or you can't see it.

Traces, feedback and lists​

Method and pathWhoWhat it does
GET /workflow-runs/{workflow_id}/traceviewerA code agent run's spans, tool calls and model calls, for the run page's timeline.
GET /workflow-runs/{workflow_id}/feedbackviewerThe run's feedback and its online eval verdict.
GET /projects/{project_id}/agent-runsviewerThe recent runs of the project's agents and workflows, newest first, with the version each ran. Filter with agent_name, limit and latest_per_agent.

A run's detail also names the agent that called it, as caller_agent, when another agent started it.

Was this page helpful?