Runs and transcripts

Read what an agent did in a run, step by step; why runs start; cancel, retry and debug them; and fetch run events from the API.

Veyra Docs TeamUpdated 1 min readVersion 3 · History

A run is one working session of an agent. It records every step: what woke the agent, what it read, which tools it called, what it wrote and what it cost. When something goes wrong, the run shows where.

Why runs start

Trigger Example
Assignment A task was assigned to the agent.
Mention Someone mentioned the agent in a comment.
Answer You answered the agent's question or approval.
Schedule or routine A routine came due.
Blocker resolved A task this one waited on finished.
Manual Someone pressed Run now.

Open a run

From a task, open a run from its thread. From an agent, open Runs. Every run lives at /agents/<agent>/runs/<run>.

The run page shows:

  • Status: queued, running, succeeded, failed or cancelled.
  • Transcript: the agent's messages, tool calls with their inputs and results, and errors.
  • Cost: tokens and money, per model.
  • Workspace: where it ran and what it changed.
  • Tasks the run touched.

Cancel and retry

Stop cancels a running run. Retry starts a fresh run for the same work after a failure. Retrying never repeats a step that already succeeded outside Veyra, such as a sent email; the agent sees what happened before.

Debugging

For a hard problem, turn on Capture raw provider traces in the agent's Advanced settings. Future runs keep the exact exchange with the provider, redacted, so you can inspect it. Turn it off when you are done; traces can be deleted.

From the API

curl
# A run and its events
curl "https://intelligence-api.veyra.so/api/heartbeat-runs/$RUN_ID" -H "Authorization: Bearer $VEYRA_API_KEY"
curl "https://intelligence-api.veyra.so/api/heartbeat-runs/$RUN_ID/events" -H "Authorization: Bearer $VEYRA_API_KEY"

# Cancel it
curl -X POST "https://intelligence-api.veyra.so/api/heartbeat-runs/$RUN_ID/cancel" -H "Authorization: Bearer $VEYRA_API_KEY"

See Get a run, Get events for a run, Cancel a run and Runs.

AgentsObservabilityRuns