Runs

A run is a single execution of an agent against an input. This guide covers the full lifecycle: triggering, watching, understanding cost, and cancelling.

Where runs live

Every agent's Runs tab in the dashboard lists every run that agent has produced — manual, scheduled, or event-driven — with their status, cost, and a quick link into the run detail page. The detail page has three tabs:

• Conversation — the agent's session replay for this run.
• Artifacts — files the agent published, with direct downloads.
• Logs — a structured execution timeline filtered to signal-level events.

Trigger a run

Runs are asynchronous. You post the input; you get a run ID back immediately and poll for progress. Use the agent's id or slug in the path.

curl -X POST https://api.levainlabs.com/api/v1/agents/support-triage/runs \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "initial_state": {
      "subject": "Cannot access my account",
      "body": "I get a 403 every time I try to log in."
    }
  }'

The body takes either initial_state (a structured payload matching the agent's state schema) or a bare prompt string. The response includes the run's id and initial status: pending. The run executes against the agent's currently active version.

Watch a run

Poll the run endpoint to see state transitions, token counts, and cost accumulating in real time:

curl https://api.levainlabs.com/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

For structured log events (what you see on the Logs tab in the dashboard):

curl https://api.levainlabs.com/api/v1/runs/$RUN_ID/log/events \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

To download the full raw log file, use GET /api/v1/runs/{run_id}/log — it returns a time-limited URL to the S3 object.

Run lifecycle

A run moves through these statuses:

Cost and token tracking

Every run tracks cost_usd, tokens_in, and tokens_out, updated live as the agent works. You can also query workspace-level analytics:

• GET /api/v1/analytics/runs/{run_id}/costs — per-run cost breakdown by model.
• GET /api/v1/analytics/usage — aggregate usage across your workspace.
• GET /api/v1/analytics/billing — daily billing roll-up.

Cancel a run

Cancellation lives on the session, not the run. Each run belongs to a session (see session_id on the run response), and cancelling that session interrupts whatever turn is currently running:

curl -X POST https://api.levainlabs.com/api/v1/sessions/$SESSION_ID/cancel \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

The orchestrator stops scheduling new steps, drains the in-flight one, and marks the run cancelled. The session is terminated as part of the same call, so you keep the event log up to the cancellation point but can't post follow-up messages to it — start a new session to continue the conversation.

Next

• Learn how the orchestrator schedules and retries your runs.
• Automate runs on a cron or from external events.
• Collect artifacts your agent publishes during the run.
• Set up BYOK to send LLM usage to your own provider account.