Check Status and Execute
Check agent runtime readiness, execute a prompt, and read support-safe run history for a specific Spinup agent.
Use these endpoints to inspect an agent runtime, send it a prompt, and read support-safe run history. See Runs for the concept. All endpoints on this page require an agent runtime key as a bearer token.
Check readiness
curl -sS "https://api.getspinup.com/v1/agents/agent_01hxyz.../status" \
-H "Authorization: Bearer sk_agent_0123456789abcdef..."Example response:
{
"daemonVersion": "2026.04.17",
"ok": true,
"status": "ready"
}/status is a read-only check. It can tell you whether capacity is already ready, but it does not start runtime admission on its own.
Execute a prompt
/exec is the admission trigger. If runtime capacity is not ready yet, Spinup queues reconciliation or provisioning and holds the request briefly within the request timeout budget. If capacity is still not ready before that bounded wait expires, the response is retryable:
{
"code": "SERVICE_UNAVAILABLE",
"data": {
"reason": "runtime_admission_provisioning",
"retryable": true,
"substrateProvider": "spinup-microvm"
},
"message": "Runtime capacity is being materialized for this agent. Please retry shortly."
}curl -sS "https://api.getspinup.com/v1/agents/agent_01hxyz.../exec" \
-H "Authorization: Bearer sk_agent_0123456789abcdef..." \
-H "Content-Type: application/json" \
-d '{
"input": "Summarize this repository and tell me the next thing you would inspect.",
"timeoutSeconds": 45
}'Example response:
{
"output": {
"text": "I would inspect apps/api/src/services/agent-runtime.ts next because it controls execution routing and timeout behavior."
}
}Optional request fields
harness: target a specific supported harness (openclaworhermes) instead of the defaultsessionId: continue a prior harness session when the runtime returns onetimeoutSeconds: cap run time for the requestworkspace: set a safe relative runtime workspace path for the requestcwd: set a safe relative runtime working directory for the request
When harness is hermes, Spinup runs the Hermes CLI inside the agent's isolated environment on Hermes' local backend. The rest of Hermes' surface (gateway, API server, messaging, cron, remote backends) isn't wired up yet; keep that part of the workload on a self-hosted Hermes setup if you need it today.
List runs
List recent runs for the same agent:
curl -sS "https://api.getspinup.com/v1/agents/agent_01hxyz.../runs?limit=20" \
-H "Authorization: Bearer sk_agent_0123456789abcdef..."Example response:
{
"hasMore": false,
"nextCursor": null,
"runs": [
{
"id": "run_01hxyz...",
"agentId": "agent_01hxyz...",
"status": "completed",
"createdAt": "2026-04-28T08:30:00.000Z",
"startedAt": "2026-04-28T08:30:01.000Z",
"completedAt": "2026-04-28T08:30:08.000Z",
"updatedAt": "2026-04-28T08:30:08.000Z",
"harness": { "requested": "openclaw", "resolved": "openclaw" },
"request": { "harness": "openclaw", "timeoutSeconds": 45 },
"output": "Done.",
"error": { "code": null, "message": null, "retryable": null },
"warnings": null,
"tokenUsage": {
"source": "provider_response",
"inputTokens": 120,
"outputTokens": 40,
"reasoningTokens": null,
"cacheReadTokens": null,
"cacheWriteTokens": null,
"totalTokens": 160
},
"toolUsage": { "source": "harness_result", "toolCallCount": 2 },
"evidence": { "stateCandidateCount": 0, "substrateProvider": "spinup-microvm" }
}
]
}Use nextCursor as the cursor query parameter for the next page.
Get one run
curl -sS "https://api.getspinup.com/v1/agents/agent_01hxyz.../runs/run_01hxyz..." \
-H "Authorization: Bearer sk_agent_0123456789abcdef..."The response shape is { "run": ... } with the same support-safe run object used by the list endpoint.
Public run history intentionally does not return the original prompt input, raw stdout/stderr, raw provider payloads, audit events, billing cost details, actor IDs, internal session IDs, Worker Host IDs, microVM IDs, or secret/env maps. It returns the final user-facing output because /exec already returns that output to the same scoped runtime key.