Documentation menu
Agent Runs

Cancel a live run

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 processing stops after the current step; the final report settles the run as canceled.
  • queued, acquiring, starting, awaitingToolResult, awaitingDelegateResult: the run transitions straight to canceled and the workflow retires any held machine.
  • canceling: retry-safe; the workflow is woken 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

  • Accepts a Studio session or a valid credential 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

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

header

NameTypeRequiredDescription
Idempotency-Keystringoptional

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)
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 has reached a terminal state that cannot be canceled. The message carries the run's current state.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)