Documentation menu
Agent Runs

Start a run

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.
  • With an Idempotency-Key, repeating the request, concurrently or later, admits at most one run and returns the response of its admission for 24 hours. Reusing the key for a different request returns 409.
  • Dispatch capacity can produce 503/429 responses with Retry-After. A request may already have been admitted, so use an Idempotency-Key when retrying.
  • 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.
  • A Project Agent Run resolves its organization from the addressed Environment and Agent.
  • For a legacy System Agent Run, a session must specify organizationId in the query. An organization-scoped credential can omit it.

Parameters

query

NameTypeRequiredDescription
organizationIdstringoptionalSelects the organization for a legacy System Agent Run. Required for a session without an Environment. Omit when addressing an Environment.

header

NameTypeRequiredDescription
Idempotency-Keystringoptional

Request body

Required — Request body for: Start a run.

application/json

Alternative 1

NameTypeRequiredDescription
agentIdstringrequiredProject or System Agent ID for the new agent run
environmentIdstringoptional
querystringrequired
contentsarray<object>optional
provider"anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks"optional
modelstringoptional
reasoningBudgetone of 2 typesoptional
subjectUserIdstringoptional

Alternative 2

NameTypeRequiredDescription
agentIdstringrequiredProject or System Agent ID for the new agent run
environmentIdstringoptional
queryunknownoptional
contentsarray<one of 3 types>required
provider"anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks"optional
modelstringoptional
reasoningBudgetone of 2 typesoptional
subjectUserIdstringoptional

multipart/form-data

NameTypeRequiredDescription
agentIdstringrequired
environmentIdstringoptional
querystringoptional
provider"anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks"optional
modelstringoptional
reasoningBudgetone of 2 typesoptional
subjectUserIdstringoptional
filesarray<file>requiredRepeat files for UTF-8 text, supported images, or PDF; each <=5 MiB, total <=10 MiB.

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)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.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 by the execution backend during admission or dispatch. The response carries a Retry-After header; use an Idempotency-Key when retrying and inspect the AgentRun state.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable while admitting or dispatching the run. Durable admission may already exist; the response carries a Retry-After header. Use an Idempotency-Key when retrying and inspect the AgentRun state.application/json — PublicApiError — error: object (required)