Runs

Execute agents and monitor run status, logs, and metrics.

Run Status Values

Status	Description
`pending`	Run is queued, waiting to start
`running`	Agent is currently executing
`completed`	Run finished successfully
`failed`	Run encountered an error
`timeout`	Run exceeded time limit
`cancelled`	Run was cancelled by user

List Runs

GET /v1/runs

Returns a paginated list of runs.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Items per page (1-100)
`cursor`	string	-	Pagination cursor
`status`	string	-	Filter by status

Request

curl "https://api.vm0.ai/v1/runs?status=completed&limit=10" \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "data": [
    {
      "id": "run_abc123",
      "agentId": "ag_xyz789",
      "agentName": "my-agent",
      "status": "completed",
      "prompt": "Research AI trends",
      "createdAt": "2024-01-15T10:00:00Z",
      "startedAt": "2024-01-15T10:00:05Z",
      "completedAt": "2024-01-15T10:15:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Create Run

POST /v1/runs

Starts a new agent execution. Returns immediately with run details; the agent executes asynchronously.

Request Body

Field	Type	Required	Description
`agent`	string	*	Agent name
`agentId`	string	*	Agent ID
`sessionId`	string	*	Continue existing session
`checkpointId`	string	*	Resume from checkpoint
`agentVersion`	string	No	Version specifier (default: `latest`)
`prompt`	string	Yes	Task prompt for the agent
`variables`	object	No	Environment variables
`secrets`	object	No	Secret environment variables
`volumes`	object	No	Volume mounts (name -> version)
`artifactName`	string	No	Artifact name to mount
`artifactVersion`	string	No	Artifact version (defaults to latest)

*One of agent, agentId, sessionId, or checkpointId is required.

Request

curl https://api.vm0.ai/v1/runs \
  -H "Authorization: Bearer vm0_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "prompt": "Research the latest AI trends and create a summary report",
    "variables": {
      "SLACK_CHANNEL_ID": "C0123456789"
    }
  }'

Response (202 Accepted)

{
  "id": "run_def456",
  "agentId": "ag_xyz789",
  "agentName": "my-agent",
  "status": "pending",
  "prompt": "Research the latest AI trends and create a summary report",
  "error": null,
  "executionTimeMs": null,
  "checkpointId": null,
  "sessionId": "sess_abc123",
  "artifactName": null,
  "artifactVersion": null,
  "createdAt": "2024-01-15T10:00:00Z",
  "startedAt": null,
  "completedAt": null
}

Get Run

GET /v1/runs/:id

Retrieves run details including execution metrics.

Path Parameters

Parameter	Type	Description
`id`	string	Run ID

Request

curl https://api.vm0.ai/v1/runs/run_abc123 \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "id": "run_abc123",
  "agentId": "ag_xyz789",
  "agentName": "my-agent",
  "status": "completed",
  "prompt": "Research AI trends",
  "error": null,
  "executionTimeMs": 900000,
  "checkpointId": "chk_xyz789",
  "sessionId": "sess_abc123",
  "artifactName": "research-output",
  "artifactVersion": "v1_abc123",
  "volumes": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "startedAt": "2024-01-15T10:00:05Z",
  "completedAt": "2024-01-15T10:15:00Z"
}

Cancel Run

POST /v1/runs/:id/cancel

Cancels a pending or running execution.

Path Parameters

Parameter	Type	Description
`id`	string	Run ID

Request

curl -X POST https://api.vm0.ai/v1/runs/run_abc123/cancel \
  -H "Authorization: Bearer vm0_live_xxx"

Response

Returns the updated run object with status: "cancelled".

Stream Events

GET /v1/runs/:id/events

Streams real-time events using Server-Sent Events (SSE).

Path Parameters

Parameter	Type	Description
`id`	string	Run ID

Query Parameters

Parameter	Type	Description
`lastEventId`	string	Resume from event ID

Request

curl https://api.vm0.ai/v1/runs/run_abc123/events \
  -H "Authorization: Bearer vm0_live_xxx" \
  -H "Accept: text/event-stream"

Event Types

Event	Description
`status`	Run status changed
`output`	Agent produced output
`error`	Error occurred
`complete`	Run finished
`heartbeat`	Keep-alive signal

Event Format

event: status
data: {"status": "running"}
id: evt_123

event: output
data: {"content": "Starting research..."}
id: evt_124

event: complete
data: {"status": "completed", "executionTimeMs": 900000}
id: evt_125

Get Logs

GET /v1/runs/:id/logs

Retrieves unified logs from the run.

Path Parameters

Parameter	Type	Description
`id`	string	Run ID

Query Parameters

Parameter	Type	Default	Description
`type`	string	`all`	Log type: `all`, `agent`, `system`, `network`
`since`	string	-	Start time (ISO 8601)
`until`	string	-	End time (ISO 8601)
`order`	string	`asc`	Sort order: `asc`, `desc`
`limit`	integer	20	Items per page
`cursor`	string	-	Pagination cursor

Request

curl "https://api.vm0.ai/v1/runs/run_abc123/logs?type=agent&limit=50" \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "data": [
    {
      "timestamp": "2024-01-15T10:00:05Z",
      "type": "agent",
      "level": "info",
      "message": "Starting execution",
      "metadata": {}
    },
    {
      "timestamp": "2024-01-15T10:00:10Z",
      "type": "agent",
      "level": "info",
      "message": "Searching for AI trends...",
      "metadata": {"tool": "web_search"}
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "xxx"
  }
}

Get Metrics

GET /v1/runs/:id/metrics

Retrieves resource usage metrics for a run.

Path Parameters

Parameter	Type	Description
`id`	string	Run ID

Request

curl https://api.vm0.ai/v1/runs/run_abc123/metrics \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "data": [
    {
      "timestamp": "2024-01-15T10:00:05Z",
      "cpuPercent": 25.5,
      "memoryUsedMb": 512,
      "memoryTotalMb": 2048,
      "diskUsedMb": 100,
      "diskTotalMb": 1000
    }
  ],
  "summary": {
    "avgCpuPercent": 30.0,
    "maxMemoryUsedMb": 1024,
    "totalDurationMs": 900000
  }
}

Run Object

Field	Type	Description
`id`	string	Unique run identifier (prefix: `run_`)
`agentId`	string	Agent that was executed
`agentName`	string	Agent name
`status`	string	Current status
`prompt`	string	Task prompt
`error`	string	Error message (when failed)
`executionTimeMs`	integer	Total execution time
`checkpointId`	string	Checkpoint for resuming
`sessionId`	string	Session identifier
`artifactName`	string	Output artifact name
`artifactVersion`	string	Output artifact version
`volumes`	object	Input volume versions
`createdAt`	string	ISO 8601 creation timestamp
`startedAt`	string	ISO 8601 start timestamp
`completedAt`	string	ISO 8601 completion timestamp

On this page