Agent Runs

List canonical Agent Runs accessible to the authenticated credential.

Scope

• Authorization is evaluated against the caller's Organization and Agent scope before pagination.
• A Project or Environment filter narrows the authorized run collection; it does not widen access.
• API keys and sessions use the same resource and operation authorization boundary.

Filtering

• projectId: Optional canonical Project filter.
• environmentId: Optional canonical Environment filter.
• agentId: Optional canonical Agent filter.
• agentJobId: Optional scheduled Agent Job firing filter.
• createdBy: Optional creator identity filter.
• states: Optional lifecycle-state filter (comma-separated list or array).

Sorting

• sort: createdAt or updatedAt.
• order: asc or desc.

Pagination

• limit: Number of Agent Runs to return (1–100, default 20).
• cursor: Opaque cursor returned in pagination.nextCursor; reuse it only with the same filters and ordering.

Response

• Returns agentRuns with canonical run ID, Agent and Agent Revision identity, actor, lifecycle state, digests, timestamps, runtime version, and content-retention metadata.
• Returns pagination with the next opaque cursor when another page is available; no separate total-count field is returned.

Authentication

• Requires a valid session or API key in the Authorization header.

Start a new Agent Run for a Project Agent or System Agent.

Ownership

• Requires agentId; Project Agents may also specify environmentId.

Agent Resolution

• The target Agent and its active revision are resolved server-side.

Provider selection

• Omit provider to use the platform default provider, model, and credential.
• Set provider to use an organization-bound credential; an explicitly selected provider never falls back to the platform credential.

Execution

• AgentRun admission persists the run and queues asynchronous dispatch to a dedicated runner; runner execution does not block the response.
• Dispatch capacity and idempotency leases can produce 503/429 responses with Retry-After. A request may already have durable admission state, so use an Idempotency-Key when retrying and inspect the AgentRun state.
• After admission the run is handed to the runner; progress is journaled as lifecycle transitions (see GET /agent-runs/:agentRunId/transitions) and can be monitored via the checkpoints endpoint.
• JSON requests may provide canonical contents; multipart requests may repeat files (ASCII text, supported images, or PDF). Files are validated and converted to inline message parts before dispatch.

Authentication

• Requires a valid session or API key in the Authorization header.

Retrieve one canonical Agent Run by its opaque run_ ID.

Ownership

• The run is resolved by its canonical ID and must be authorized in the caller's Organization and Agent scope.
• A run retains the Agent and immutable Agent Revision identity selected at admission; it is not rebound to a newer revision.

Response

• Returns the public Agent Run record, including Agent and Agent Revision identity, actor references, lifecycle state, digests, timestamps, runtime version, content-retention metadata, and the optional last-activity projection.
• The response does not expose internal execution tables, provider details, token statistics, or a separate step collection.

AgentRun Lifecycle States

• queued: Accepted; no live attempt
• acquiring: Attempt opened; machine lease in progress
• starting: Machine leased; runner handoff and runtime boot
• running: Runtime executing
• awaitingToolResult: Paused for an interactive tool result
• awaitingDelegateResult: Paused for an external delegate result
• canceling: Cancel requested; runtime winding down
• completed / failed / canceled / expired: Terminal

Authentication

• Requires a valid session or API key in the Authorization header.
• The credential must be authorized for the run's Agent Run operation and resource scope.

Cancel a run. The outcome depends on the run's lifecycle state:

• running: the run transitions to canceling and the execution worker is signaled to stop after the current step; its final report settles the run as canceled.
• queued, acquiring, starting, awaitingToolResult, awaitingDelegateResult: the run transitions straight to canceled and any held machine is released.
• canceling: retry-safe; the execution worker is signaled again and the current run is returned.
• canceled: already satisfied; the current run is returned.
• completed, failed, or expired: 409 Conflict; the message carries the run's current state.

Authentication

• Requires a valid API key supplied in the Authorization header.
• The caller must be authorized for the run's Project and Environment operation scope. No tenant ID is accepted; the run is resolved server-side by its canonical ID.

Returns one row per persisted checkpoint artifact for the run.

Use the returned identifiers to fetch any checkpoint resources needed by the client.

Authentication

• Requires session or API key with operation agent-runs:checkpoints:list
• The caller must be authorized for this operation within the run's owning organization and its persisted Project, Environment, or Agent scope

Retrieve the latest persisted checkpoint for an AgentRun together with its runtime checkpoint and step payload. The lookup is scoped to the caller's organization and operation-specific Project, Environment, or Agent access, and uses the same latest selector as run continuation.

Authentication

• Requires session or API key with operation agent-runs:steps:checkpoints:get
• Automated-run credentials must be bound to the run's agent revision

Continue an agent run in a resumable state in the specified project agent. When a checkpoint exists the run resumes from the latest one; otherwise it starts a fresh attempt with the provided query. Approval decisions are processed by the operation-approval resource and enqueue a durable, server-owned resume. This endpoint accepts only an ordinary authorized continuation query; it cannot carry an approval decision or privileged resume signal.

Ownership

• The persisted execution target identifies the project agent (or system agent)
• AgentRun must belong to that persisted target

Use Cases

• Respond to interactive tool requests.
• Add the next user message to a completed run (multi-turn chat). Attachments are start-only; a continuation must provide any new message content explicitly and never replays the original attachment payload.
• Retry after failure or after a cancel.

State Requirements

• AgentRun must be in a resumable state: completed, awaitingToolResult, failed, or canceled. expired is dead and rejects with 409; an externally waiting run rejects with 400. A live state (queued/acquiring/starting/running/canceling) rejects with 409 Conflict; the response message carries the run's current state.

Authentication

• Requires a valid session or API key in the Authorization header
• The credential must be authorized for the persisted execution target

Provider selection

• Omit provider to retain the run's original credential source.
• Set provider to explicitly select a configured provider; it never falls back to the platform credential.

List all agent steps for a specific run.

Sorting

• sort: Sort by createdAt or updatedAt
• order: Sort order (asc or desc)

Pagination

• limit: Number of results to return (1-100, default 20)
• cursor: Opaque cursor returned in pagination.nextCursor.

Depth

• depth: Tree depth for nested step responses (0-10, default 0)
• 0: Flat list of all steps (default)
• 1: Root steps only (parentAgentStepId is null) with lastCheckpointId and empty childAgentSteps
• 2+: Root steps with nested childAgentSteps up to the specified depth

Response

• Returns steps with full details
• Each step includes agent information and execution context
• Includes total count for pagination

Authentication

• Requires a valid session or API key in the Authorization header

Retrieve detailed information about a specific step.

Response

• Returns full step details
• Includes agent information and execution context

AgentStep Data

• Step execution details (timing, token usage)
• Agent information used for the step
• Status and execution metadata

Authentication

• Requires a valid session or API key in the Authorization header
• The caller must have operation-specific access to the run's owning organization and persisted Project, Environment, or Agent scope

Stream live runtime telemetry for an agent run via Server-Sent Events (SSE).

• Runtime PerstackEvent objects are relayed as message events.
• ping events are transport keepalives only.
• Lifecycle state is not part of this stream. Use GET /agent-runs/:id for current state, /transitions for lifecycle history, and checkpoints for durable runtime history/replay.
• The route performs auth/resource/state/runner-attach preflight before the SSE body starts. Non-live states return HTTP status: 409 when no live runtime stream exists, 503 + Retry-After when the run is not ready or runner attachment is temporarily unavailable.

Authentication

• Requires a valid session or API key in the Authorization header

Return the run's full transition journal in seq order. Every lifecycle change (queued→acquiring, …, terminal) is one journal entry carrying the acting component, the attempt it belongs to, and an optional reason.

Authentication

• Requires a valid session or API key in the Authorization header
• The credential must be authorized for the canonical Agent Run operation and its Organization/Project/Environment/Agent resource scope