Skip to main content
POST
/
v1
/
agent-deployments
/
{deployment_id}
/
runs
Create an agent run
import requests

url = "https://api.13-215-85-171.sslip.io/v1/agent-deployments/{deployment_id}/runs"

payload = {
    "version_id": "<string>",
    "input": {},
    "envs": {},
    "retain_on_failure": True,
    "retention_seconds": 2
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
{
  "id": "adrun_1234abcd",
  "deployment_id": "<string>",
  "version_id": "<string>",
  "input": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "retain_on_failure": true,
  "retention_seconds": 2,
  "sandbox_id": "<string>",
  "process_id": 123,
  "exit_code": 123,
  "failure_reason": "<string>",
  "output_manifest": {},
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Headers

​
Idempotency-Key
string
required

Reuse the same key to safely retry the same create, reusable snapshot create, fork, upload create/complete, or agent deployment create operation without duplicating work.

Path Parameters

​
deployment_id
string
required

Agent deployment ID

Body

application/json
​
version_id
string | null
​
input
object

Free-form run input supplied at run creation; passed through to the agent verbatim, deliberately open.

​
envs
object
write-only

Request-only runtime environment variable values. P0 accepts string values only; future secret references are reserved by AgentSecretReference. Values are injected into agent processes and are not stored in deployment config, run, service, or platform event records.

​
retain_on_failure
boolean | null
​
retention_seconds
integer<int64> | null
Required range: x >= 1

Response

Agent run created

​
id
string
required
Example:

"adrun_1234abcd"

​
deployment_id
string
required
​
version_id
string
required
​
mode
enum<string>
required
Available options:
job,
service
​
status
enum<string>
required
Available options:
queued,
starting,
installing,
running,
succeeded,
failed,
cancelled,
timed_out
​
input
object
required

Free-form run input supplied at run creation; passed through to the agent verbatim, deliberately open.

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
retain_on_failure
boolean | null

Per-run override for failed job sandbox retention. Omit to use deployment debug config.

​
retention_seconds
integer<int64> | null

Retention TTL in seconds when the run is retained. Defaults to 3600 if retention is enabled without an explicit TTL.

Required range: x >= 1
​
sandbox_id
string | null
​
process_id
integer<uint32> | null
​
exit_code
integer | null
​
failure_reason
string | null
​
output_manifest
object

Output manifest produced by the agent runtime (typically containing an outputs array). Deliberately open: the manifest shape is owned by the agent, not the control plane.

​
started_at
string<date-time> | null
​
completed_at
string<date-time> | null
​
idempotency_key
string | null