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, credits used, and a quick link into the run detail page. The detail page has three tabs:

• Conversation — the agent's session replay for this run.
• Files — 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:

Waiting for input

An agent can pause mid-run and ask you a question. When a recipe node calls interrupt(), the run stays running but the harness stops dispatching new steps 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.

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 run 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 tracking

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.

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.

Notifications

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, and human input requests) 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 activity

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.

Next

• 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.