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
providerandmodelto 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 repeatfiles(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
| Name | Type | Required | Description |
|---|---|---|---|
organizationId | string | optional | Selects the organization for a legacy System Agent Run. Required for a session without an Environment. Omit when addressing an Environment. |
header
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | optional |
Request body
Required — Request body for: Start a run.
application/json
Alternative 1
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | required | Project or System Agent ID for the new agent run |
environmentId | string | optional | |
query | string | required | |
contents | array<object> | optional | |
provider | "anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks" | optional | |
model | string | optional | |
reasoningBudget | one of 2 types | optional | |
subjectUserId | string | optional |
Alternative 2
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | required | Project or System Agent ID for the new agent run |
environmentId | string | optional | |
query | unknown | optional | |
contents | array<one of 3 types> | required | |
provider | "anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks" | optional | |
model | string | optional | |
reasoningBudget | one of 2 types | optional | |
subjectUserId | string | optional |
multipart/form-data
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | required | |
environmentId | string | optional | |
query | string | optional | |
provider | "anthropic" | "google" | "openai" | "deepseek" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "fireworks" | optional | |
model | string | optional | |
reasoningBudget | one of 2 types | optional | |
subjectUserId | string | optional | |
files | array<file> | required | Repeat files for UTF-8 text, supported images, or PDF; each <=5 MiB, total <=10 MiB. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
402 | Payment 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) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Rate 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) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service 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) |