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.

Trigger a run

Runs are asynchronous. You post the config; you get a run ID back immediately and poll (or stream logs) for progress. agent_id is the UUID from the agent's detail endpoint.

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

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 a step-by-step view of what the agent is doing, stream the logs:

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

Logs surface the same events that get written to the session — every tool call, every decision, every intermediate result.

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

Sometimes you know a run is no longer useful. Cancel it cleanly:

curl -X POST https://api.levainlabs.com/api/v1/runs/$RUN_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 stays intact so you can inspect what happened up to the cancellation point.

Next

• Learn how the orchestrator schedules and retries your runs.
• Set up BYOK to send LLM usage to your own provider account.