Runs and traces
Everything that takes more than a moment in Orchestrate is a run on the orchestration engine: agent conversations, model builds and deploys, document ingestion, voice tool calls and eval runs. A run keeps its state if a service restarts, and it can wait for hours, for example for an approval, without holding any resources.
The runs list
Open Runs & Traces to see the most recent runs. Each row shows:
- the type: Agent, Tool, Model build, Deploy, Ingest or Eval
- the status: Running, Completed, Failed, Canceled, Terminated or Timed out
- the project, when the run belongs to one
- when it started and how long it took
- for a running agent, which step it is on, and Waiting for approval if a person needs to decide something
Filter by status or project, or search by workflow ID or type.
The list shows runs in the projects you have a role on. Runs that belong to no project, such as model builds and document ingestion, are shown to platform admins only. Orchestrate reads the 20 most recent runs on the platform and then hides the ones you can't see, so you may see fewer than 20.
Open a run
Choose a run to see its page. For an agent run, the page shows:
- the input and who started it
- each step with its status, start and end time and the number of model calls
- each tool call, with its arguments, result, duration and whether it failed
- the step's output
- every approval on the run: who approved or rejected it, or that nobody decided in time
- for a run that did not finish, Why it stopped, in the run's own words
While a run is still going, the page updates as it moves through its steps. Developers and admins can stop it with Cancel, which is audited.
The page also shows:
- for a workflow graph, which branch was taken, which steps were skipped and each loop pass
- for a code agent run, a timeline of its spans: steps, model calls and tool calls, from the traces the agent sends
- Called by, when another agent started the run
- the run's Feedback: thumbs and comments from the people who used it, and its online eval verdict. See Online evals and feedback.
Stored inputs, answers, tool arguments and results are redacted for personal data. See PII guardrails.
| Status | Meaning |
|---|---|
| Running | Still working, or waiting for an approval. |
| Completed | Finished. |
| Failed | Stopped with an error. A rejected approval also ends a run as failed, with the reason. |
| Terminated or Canceled | Someone ended the run from the orchestration engine. No error was recorded. |
| Timed out | The run went past its time limit. |
The trace in the API
When you run an agent through the API, the finished result carries the same trace:
result.final: the agent's answerresult.outputs: each step's output, by step nameresult.trace: one entry per step, listing its model, its tool calls with arguments, results, duration and approval, how many model calls it used, and token counts when the model reported them
To follow a run that is still going, read GET /workflow-runs/{workflow_id}. It returns live progress, open and closed approvals, and the failure reason if there is one.
Debugging a run
- The tool was never called. Check the step's tool calls. If there are none, the model answered from its own knowledge. Make the system prompt say when to use the tool, or try a larger model.
- The tool was called wrongly. Look at the arguments in the trace. Improve the tool's description so the model knows what to send.
- The tool returned something unhelpful. Look at the result in the trace. Results that start with
Errorare marked as failed. - The run is stuck on Running. Check for Waiting for approval. If there is no open approval and the run is on a model call, the model may be slow. Each model call attempt times out after two minutes, and a failed call is tried up to three times before the run fails. Check that the model is deployed and answers in the Playground.
- The run failed on a model call. If the Model Gateway refused the call, for example with
Denied by policyor a guardrail refusal, the run fails at once with that reason. Read Why it stopped.
Your operator can see every run in the Temporal UI, including the last error of a call that is being retried. The Temporal UI is not exposed outside the cluster. See Operations.