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 liveCopy Anchor Link

Usage → Agents in the dashboard lists every agent; drilling into one shows every run it has produced — manual, scheduled, or event-driven — grouped by conversation, with status, credits used, and a link into each run's detail page (the agent page's Usage tab jumps straight there). The run detail page has two tabs:

• Usage — credits, tokens, cost by model, and the LLM request log.
• Logs — a structured execution timeline filtered to signal-level events.

The conversation itself and any files the agent published live in the agent's Chats tab; conversations with files are marked in the list.

Trigger a runCopy Anchor Link

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 runCopy Anchor Link

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 lifecycleCopy Anchor Link

A run moves through these statuses:

Waiting for inputCopy Anchor Link

An agent can pause mid-turn and ask you a question. When a recipe node calls interrupt(), the run ends succeeded with paused: true — the turn's result is the question — and the session stays parked until you reply. Levain sends a human_input_requested notification — in-app by default, or to a configured Slack channel — with the agent's last message as the body and a link back to the session. Org webhook endpoints get a run.paused event instead of run.succeeded, carrying that same message under message.

Reply in-app from the session's conversation panel, or reply in the Slack thread if you've routed notifications there. The reply resumes the agent exactly where it paused; no new session is created. Subsequent replies in the same session become follow-up turns.

You can also send a message to a run that is still actively executing — without waiting for an explicit pause. The platform queues your message and folds it into the agent at the next safe step boundary. Send it from the session's conversation panel the same way as any other reply.

Cost and token trackingCopy Anchor Link

Every run tracks cost_usd, tokens_in, and tokens_out, updated live as the agent works. The dashboard shows this as Credits — the margin-inclusive billed amount, matching the usage page — while cost_usd in the API is the raw provider cost, useful for the per-model and per-request breakdowns on the run's Cost tab. 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.

Export a run recordCopy Anchor Link

When your customer asks what an agent did on their behalf, you can hand them the record. GET /api/v1/runs/{run_id}/record exports one finished run as a self-contained JSON document; GET /api/v1/runs/{run_id}/record/html renders the same record as a printable page that carries your workspace name — and no Levain branding — so you can forward it as your own.

# JSON record
curl https://api.levainlabs.com/api/v1/runs/$RUN_ID/record \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

# Printable rendition
curl https://api.levainlabs.com/api/v1/runs/$RUN_ID/record/html \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" > record.html

With an org-scoped key, X-Workspace-Id selects which workspace's run to export; workspace-scoped keys can omit it. The record is available once the run finishes. It's not available for managed agents published by Levain (their execution internals stay private); for managed agents published by your organization, export requires an organization-scoped API key.

What the record includes — and what it omitsCopy Anchor Link

The record is built for forwarding, so redaction is structural: the fields below are all it ever contains.

Included:

• The agent's name, the version number it executed, run status, and the requested / started / finished timestamps.
• Every tool call, as tool name + timestamp.
• Human approvals with the approver: workspace-member actions recorded against the run or against the agent version it executed — most commonly, who published the version that this run ran.
• The cost line: billed model usage, billed compute time (and seconds), their total, and token counts.

Omitted — never part of the record:

• Tool inputs and tool outputs.
• Prompts, model responses, and log messages.
• Secrets, credentials, and connected-integration details.
• Admin-only activity (billing, membership, and settings changes).

A customer must not see the run's raw execution log — it carries prompts, intermediate reasoning, and tool payloads. Keep GET /api/v1/runs/{run_id}/log and /log/events for your own debugging, and share only the record.

Cancel a runCopy Anchor Link

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.

NotificationsCopy Anchor Link

You can opt into in-app, email, and Slack notifications for an agent's runs. Enable Run notifications on an agent's Settings card in the dashboard — the toggle is off by default. When on, you receive an in-app notification when a run completes, and an email when a run fails.

To route notifications to Slack, connect the Slack integration and pick a default channel under Settings → Notifications. Once set, notification types you've opted into (run completed, run failed, human input requests, and automatic improvements) are delivered to that channel. A reply in the Slack thread resumes any run that is waiting for input.

You control which channels each notification type uses — and the email address and Slack channel they go to — under Settings → Notifications in the dashboard. Channels can also be updated from the API:

# Read current settings
curl https://api.levainlabs.com/api/v1/notifications/settings \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

# Update routing: send run-failed to both in-app and email
curl -X PUT https://api.levainlabs.com/api/v1/notifications/settings \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": {
      "run_failed": {"in_app": true, "email": true},
      "run_completed": {"in_app": true, "email": false}
    }
  }'

The in-app feed is available at GET /api/v1/notifications (most recent 50 items, unread count included). Mark individual items read with POST /api/v1/notifications/{notification_id}/read, or clear the whole badge with POST /api/v1/notifications/read-all.

Workspace activityCopy Anchor Link

The Activity page in the sidebar gives you a workspace-wide audit trail — runs, version publishes, member changes, integration events, and credit top-ups — newest first. Members see operational events; admins also see sensitive events (membership, settings, credits).

# Fetch the activity feed (keyset-paginated, newest first)
curl "https://api.levainlabs.com/api/v1/activity" \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

# Filter to run events only
curl "https://api.levainlabs.com/api/v1/activity?resource_type=run" \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

The response includes a cursor field; pass it as ?cursor=... to page through older events.

NextCopy Anchor Link

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