Agent Runs: How the AI Processes Your Messages

A Run represents one full agent turn from the moment you send a message to when the agent finishes processing. Every time you post a message to a chat, the API creates a Run behind the scenes. It tracks the agent’s execution lifecycle, including status changes, tool calls, streaming output, and final completion.

The Run object

string

Unique identifier for the run.

string

The chat this run belongs to.

string

Current status of the run: pending, running, completed, failed, or cancelled.

string

ISO 8601 timestamp of when the run was created.

string

ISO 8601 timestamp of the last update to the run.

Lifecycle

When you send a message, the Run moves through the following states:

pending — the run is queued and waiting to start.
running — the agent is actively executing, making tool calls and generating output.
completed, failed, or cancelled — the run has finished.

Only one run can be active per chat at a time. If you send a new message while a previous run is still running, the API queues the new run until the current one completes.

Cancelling a run

You can stop an active run at any time. Any credits reserved but not yet consumed are released back to your balance.

curl -X POST http://localhost:3000/api/v1/runs/{runId}/cancel \
  -H "Authorization: Bearer <clerk-session-token>"

Realtime streaming

To follow a run’s progress in real time, request a short-lived token and subscribe to the event stream via Trigger.dev realtime.

1. Get a realtime token

curl http://localhost:3000/api/v1/runs/{runId}/realtime-token \
  -H "Authorization: Bearer <clerk-session-token>"

The response returns a token you use in the next step.

import { TriggerRealtime } from '@trigger.dev/realtime';

const client = new TriggerRealtime({ token: '<realtime-token>' });

const stream = client.subscribe('run-events', { runId: '<runId>' });

stream.on('event', (event) => {
  console.log('Run event:', event);
});

stream.on('complete', () => {
  console.log('Run finished');
});

Error states

If a run fails due to insufficient credits, it ends with a 402 admission error before any provider call is made. This protects your balance from partial execution charges. For more details on how credits are reserved and refunded, see Credits. Runs can also fail due to provider errors or invalid tool responses. In all failure cases, the run status becomes failed and the error details are available through the event stream or by fetching the run directly.

Chats

Learn how to create chats and send messages that trigger runs.

Waitpoints

Discover how runs pause and resume for human-in-the-loop interactions.

Get Started

Core Concepts

Reference

Agent Runs: How the AI Processes Your Messages

The Run object

Lifecycle

Cancelling a run

Realtime streaming

1. Get a realtime token

Error states

Chats

Waitpoints

​The Run object

​Lifecycle

​Cancelling a run

​Realtime streaming

​1. Get a realtime token

​2. Subscribe to the stream

​Error states

​Related concepts

Chats

Waitpoints

The Run object

Lifecycle

Cancelling a run

Realtime streaming

1. Get a realtime token

2. Subscribe to the stream

Error states

Related concepts