Agent Runs

GET /api/v1/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.
• agentRunId: Optional exact Agent Run filter; combined with the other filters, it returns the run only when every filter matches.
• 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 size.
• 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.

Parameters

query

Responses

POST /api/v1/agent-runs

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

• Project Agents require a configured Project model policy. Omit provider and model to use that policy's default; explicit selections must be allowed by the policy and eligible for the immutable Environment configuration.
• Credentials come from the configuration's pinned Organization binding or the deployment-managed provider route. Selecting a provider does not select a credential source. Unavailable bindings are rejected without fallback.
• System Agents use the deployment's default provider/model and credentials.

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 (UTF-8 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.

Parameters

header

Request body

Required — Request body for: Start a run.

application/json

multipart/form-data

Responses

GET /api/v1/agent-runs/{agentRunId}

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, and content size.
• 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.

Parameters

path

Responses

GET /api/v1/agent-runs/{agentRunId}/available-models

Parameters

path

Responses

POST /api/v1/agent-runs/{agentRunId}/cancel

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.

Parameters

path

header

Responses

GET /api/v1/agent-runs/{agentRunId}/checkpoints

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

Parameters

path

query

Responses

GET /api/v1/agent-runs/{agentRunId}/checkpoints/latest

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

Parameters

path

Responses

POST /api/v1/agent-runs/{agentRunId}/continue

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). Optional contents attach new files to this turn. Original attachment payloads are not replayed as new input.
• 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 and model to keep the Run's last recorded selection. Historical Runs without a record require both provider and model explicitly.
• Project Agent selections are rechecked against the current Project model policy and the Run's persisted Environment configuration. A removed selection is rejected; it is never silently replaced by the policy default.
• Credentials are resolved from the pinned binding or deployment route at continuation time. Unavailable credentials are rejected without fallback.

Parameters

path

header

Request body

Required — Request body for: Continue a run.

application/json

Responses

GET /api/v1/agent-runs/{agentRunId}/steps

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
• pagination.count is the number of steps in this page

Authentication

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

Parameters

path

query

Responses

GET /api/v1/agent-runs/{agentRunId}/steps/{agentStepId}

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

Parameters

path

Responses

GET /api/v1/agent-runs/{agentRunId}/steps/{agentStepId}/checkpoints/{checkpointId}

Parameters

path

Responses

HEAD /api/v1/agent-runs/{agentRunId}/steps/{agentStepId}/checkpoints/{checkpointId}

Parameters

path

Responses

GET /api/v1/agent-runs/{agentRunId}/stream

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 stream is bound to the run attempt it attached to. It closes when that attempt's runtime telemetry ends, or within about two seconds after the run leaves its live state (running / canceling) or the attached attempt ends, whether or not a terminal runtime event was relayed. Read GET /agent-runs/:id for the outcome, and re-attach only when that state is live again.
• 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

Parameters

path

Responses

GET /api/v1/agent-runs/{agentRunId}/transitions

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

Parameters

path

query

Responses

GET /api/v1/agent-runs/{agentRunId}/work-memory-reads

Returns every long-term memory read the run's work-memory delegate performed, oldest first: which past run it read and whether it saw an excerpt, the summary, or the transcript.

Parameters

path

Responses