Check Status and Run

Check agent runtime readiness, start durable work, and read support-safe run history for a specific Spinup agent.

Use these endpoints to inspect an agent runtime, start durable runs, 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,
  "readiness": {
    "state": "ready",
    "retryable": false,
    "reason": null,
    "nextAction": "Runtime status is ready. You can start a run.",
    "activeRelease": {
      "id": "agent_release_01hxyz...",
      "required": true,
      "stateVersionId": "state_version_01hxyz..."
    },
    "defaultHarness": {
      "name": "openclaw",
      "ready": true,
      "reason": null
    },
    "model": {
      "ready": true,
      "reason": null,
      "selected": {
        "provider": "openrouter",
        "model": "openai/gpt-4o-mini"
      }
    },
    "degradedReasons": []
  },
  "status": "ready"
}

Non-ready example:

{
  "ok": false,
  "status": "not_ready",
  "readiness": {
    "state": "cold",
    "retryable": true,
    "reason": "runtime_capacity_not_materialized",
    "nextAction": "Start a run to trigger runtime admission for this agent.",
    "activeRelease": {
      "id": "agent_release_01hxyz...",
      "required": true,
      "stateVersionId": "state_version_01hxyz..."
    },
    "defaultHarness": {
      "name": "openclaw",
      "ready": true,
      "reason": null
    },
    "model": {
      "ready": true,
      "reason": null,
      "selected": {
        "provider": "openrouter",
        "model": "openai/gpt-4o-mini"
      }
    },
    "degradedReasons": []
  }
}

/status is a read-only check. It can tell you whether capacity is already ready, cold, reconciling, provisioning, degraded, blocked, or under backpressure, but it does not start runtime admission on its own. Use readiness.state, readiness.retryable, and readiness.nextAction for automation. Only top-level status: "ready" with ok: true means the existing runtime can answer a private status check. Non-ready observations return status: "not_ready" with ok: false. cold means no compatible runtime capacity is currently materialized. blocked usually means the agent needs an active deploy or configuration repair. reconciling and provisioning mean existing lifecycle work must finish. degraded means Spinup has support-safe failure evidence. backpressure means queued or running work is already consuming the relevant runtime limit.

Start A Run

POST /runs accepts a prompt input, optional run controls, and an optional idempotencyKey. Spinup creates a queued run before dispatching it and returns a run handle quickly. The response does not echo the prompt input.

curl -sS "https://api.getspinup.com/v1/agents/agent_01hxyz.../runs" \
  -H "Authorization: Bearer sk_agent_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Audit the repository and write a migration plan.",
    "model": {
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4-5",
      "maxOutputTokens": 32000
    },
    "timeoutSeconds": 1800,
    "idempotencyKey": "audit-2026-06-14"
  }'

Example response:

{
  "run": {
    "id": "run_01hxyz...",
    "agentId": "agent_01hxyz...",
    "status": "queued",
    "createdAt": "2026-06-14T08:30:00.000Z",
    "startedAt": null,
    "completedAt": null,
    "updatedAt": "2026-06-14T08:30:00.000Z",
    "harness": { "requested": null, "resolved": null },
    "model": {
      "requested": {
        "provider": "openrouter",
        "model": "anthropic/claude-sonnet-4-5",
        "maxOutputTokens": 32000
      },
      "resolved": {
        "provider": "openrouter",
        "model": "anthropic/claude-sonnet-4-5",
        "maxOutputTokens": 32000
      }
    },
    "request": {
      "model": {
        "provider": "openrouter",
        "model": "anthropic/claude-sonnet-4-5",
        "maxOutputTokens": 32000
      },
      "timeoutSeconds": 1800
    },
    "output": null,
    "error": { "code": null, "message": null, "retryable": null },
    "warnings": null,
    "tokenUsage": {
      "source": null,
      "inputTokens": null,
      "outputTokens": null,
      "reasoningTokens": null,
      "cacheReadTokens": null,
      "cacheWriteTokens": null,
      "totalTokens": null
    },
    "toolUsage": { "source": null, "toolCallCount": null },
    "evidence": {
      "failureClass": null,
      "nextAction": null,
      "phase": "queued",
      "phaseUpdatedAt": "2026-06-14T08:30:00.000Z",
      "retryable": null,
      "stateCandidateCount": 0,
      "substrateProvider": null
    }
  }
}

Poll the returned run ID with GET /runs/{runId} until status is completed, failed, or timed_out. queued means the run is accepted but not executing yet. running means Spinup has claimed and started execution. evidence.phase gives bounded support-safe progress such as dispatching, admitting_runtime, projecting_state, executing_harness, or finalizing.

If you send the same idempotencyKey with the same normalized request and the same scoped agent runtime key, Spinup returns the existing run. Reusing the key with a different request returns a conflict.

Optional request fields

harness: target a specific supported harness (openclaw or hermes) instead of the default
model: override the active release model for this run with { provider, model, maxOutputTokens? }
sessionId: continue a prior harness session when the runtime returns one
timeoutSeconds: cap run time for the request, up to 1800 seconds
workspace: set a safe relative runtime workspace path for the request
cwd: set a safe relative runtime working directory for the request

Model overrides must use a supported provider, a model identifier accepted by that provider, and the matching provider credential available to the workspace.

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" },
      "model": {
        "requested": null,
        "resolved": {
          "provider": "openrouter",
          "model": "openai/gpt-4o-mini",
          "maxOutputTokens": 64000
        }
      },
      "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": {
        "failureClass": null,
        "nextAction": null,
        "phase": "finalizing",
        "phaseUpdatedAt": "2026-04-28T08:30:07.000Z",
        "retryable": null,
        "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 for completed runs.

Check readiness

Start A Run

Optional request fields

List runs

Get one run

On this page