Documentation menu
Agent Runs

Continue a run

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

NameTypeRequiredDescription
agentRunIdstringrequiredIdentifies the agent run whose state or history is addressed. Applies to Continue a run.

header

NameTypeRequiredDescription
Idempotency-Keystringoptional

Request body

Required — Request body for: Continue a run.

application/json

NameTypeRequiredDescription
querystringrequired
contentsarray<one of 3 types>optional
provider"anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks"optional
modelstringoptional
reasoningBudgetone of 2 typesoptional

Responses

StatusDescriptionBody
200Response for status 200application/json — object — data: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
402Payment required. The organization has exhausted its billing-period minute budget. Upgrade the plan or wait for the period to roll over.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Conflict. The run is not in a resumable state (it is live, expired, or another request queued it first). The message carries the run's current state. The response may include a safe details.conflictReason classification.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Rate limited while starting the run. The run is left in its prior resumable state. Retry-After header set.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable. Execution capacity could not secure a runner right now. The run is left in its prior resumable state. Retry-After header set.application/json — PublicApiError — error: object (required)