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
/workflows/runsThe 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[].idstringoptionalworkflow_id.runs[].workflow_typestringoptionalAgentRunWorkflow, BuildModelImageWorkflow, DeployModelWorkflow, IngestDocumentWorkflow, EvalRunWorkflow or ExecuteToolWorkflow.runs[].statusstringoptionalRUNNING, COMPLETED, FAILED, CANCELED, TERMINATED or TIMED_OUT.runs[].project_idstring or nulloptionalruns[].start_timestringoptionalruns[].close_timestring or nulloptionalruns[].pending_approvalsarrayoptionalruns[].progressobject or nulloptionalGet a run
/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
statusstringoptionalprogressobject or nulloptionalinput, started_by, steps and current. null for other run types.progress.steps[]objectoptionalname, model, tools, status (pending, running, done, failed or canceled), started_at, finished_at, model_calls, tool_calls, output and error.progress.currentobject or nulloptionalkind is model_call, approval_check, awaiting_approval or tool_call, with the step and when it started.pending_approvalsarrayoptionalresolved_approvalsarrayoptionalfailureobject or nulloptionaltype, message, non_retryable and detail. A rejected approval has type ApprovalRejected.Responses
List a run's approvals
/workflow-runs/{workflow_id}/approvalsWhat the run is waiting for, and what it has already been told. Needs any role on the run's project.
Response fields
pendingarrayoptionalpending[].approval_idstringoptionalpending[].stepstringoptionalpending[].tool_namestringoptionalpending[].argumentsobjectoptionalpending[].reason_gatedstringoptionalpolicy when policy required approval, always when the step requires it for every call.pending[].requested_bystringoptionalpending[].requested_atstringoptionalpending[].expires_atstringoptionalresolvedarrayoptionaldecision (approve or reject), actor, reason, timed_out and decided_at.statusstringoptionalDecide an approval
/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
decisionstringrequiredapprove or reject.reasonstringoptionalResponse fields
workflow_idstringoptionalapprovalobjectoptionalResponses
decision is not approve or reject.detail says which, and by whom.Cancel a run
/workflow-runs/{workflow_id}/cancelStops 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
Traces, feedback and lists
| Method and path | Who | What it does |
|---|---|---|
GET /workflow-runs/{workflow_id}/trace | viewer | A code agent run's spans, tool calls and model calls, for the run page's timeline. |
GET /workflow-runs/{workflow_id}/feedback | viewer | The run's feedback and its online eval verdict. |
GET /projects/{project_id}/agent-runs | viewer | The 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.