Get an agent run | CloudRaker documentation

{
  "object": "string",
  "id": "agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "agent": {
    "id": "string",
    "name": "string",
    "version": 1.1
  },
  "input": {
    "files": [
      {
        "id": "string"
      }
    ]
  },
  "status": "queued",
  "progress": {
    "tasks": {
      "total": 1.1,
      "completed": 1.1
    }
  },
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "executor": "agent",
      "status": "pending",
      "summary": "string",
      "completedAt": "string",
      "note": "string"
    }
  ],
  "statusUrl": "string",
  "createdAt": "string",
  "expiresAt": "string",
  "finishedAt": "string",
  "waiting": {
    "approvals": 1.1,
    "tasks": 1.1,
    "summary": "string"
  },
  "paused": {
    "reason": "model_error"
  },
  "approvals": [
    {
      "id": "string",
      "kind": "before",
      "action": "string",
      "requestedAt": "string",
      "files": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "rationale": "string",
      "params": {}
    }
  ],
  "incomplete": true,
  "result": "string",
  "output": {
    "files": [
      {
        "id": "string",
        "name": "string",
        "url": "string"
      }
    ]
  },
  "error": {
    "code": "string",
    "message": "string"
  },
  "metadata": {}
}

Returns an agent run: where it is, the state of every step, what it is waiting on, and what it produced.

tasks[] is the step ledger. executor: "human" steps are yours to complete; summary is what the agent recorded when a step closed.
approvals[] lists the sign-offs the run is blocked on, each with the proposed params and files.
waiting counts both at a glance while status is waiting.
result and output.files carry the outcome.
agent.id and input.files are the immutable recipe for starting a successor after any terminal result.

Long-polling. ?wait=<seconds> (0–120) holds the request until the run finishes or blocks on a person.

A paused run is not a failure: it stopped short, kept everything it produced, and can be started again. Nothing an agent run imported or attached is ever taken back.

Reading a queued run is also what starts it once its files are ready, so poll it rather than waiting. expiresAt is the run’s deadline — an unfinished run parks itself for good when it passes, so a human step has to land before then.

Learn more: Agents guide

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired>=1 character

Query parameters

waitintegerOptional0-120Defaults to 0

How many seconds to hold the request open. Releases early the moment the run finishes or blocks on a person. Maximum 120; 0 returns immediately.

Response

The run.

object"agent_run"

idstring

agentobject

inputobject

statusenum

Where the agent run is in its life.

Status	Meaning
`queued`	Accepted; its files are still being prepared
`processing`	The agent is working
`waiting`	Blocked on a person — see `waiting`, `approvals` and `tasks[]`
`paused`	Stopped short of finishing and resumable; not a failure
`completed`	Finished; `result` and `output` are populated
`failed`	Finished without producing a result
`cancelled`	Stopped on request
`expired`	Reached its `expiresAt` without finishing

completed, failed, cancelled and expired are terminal. A completed run that still had outstanding work also carries incomplete: true.

progressobject

taskslist of objects

statusUrlstring

createdAtstring

expiresAtstring or null

The run’s deadline: about seven days after it starts, an unfinished run parks itself for good and its status becomes expired. null once the run is finished. Files and anything the run already filed are never taken back.

finishedAtstring or null

waitingobjectOptional

What is blocking the run. Present while status is waiting.

pausedobjectOptional

Why the run parked. Present while status is paused. A paused run keeps everything it produced and can be started again.

approvalslist of objectsOptional

Sign-offs the run is waiting on, oldest first.

incompletebooleanOptional

Present and true on a completed run that still had outstanding work — read tasks[] to see what.

resultstringOptional

The agent's closing summary.

outputobjectOptional

Files attached to the run while its steps were completed, each with a signed download link valid for about an hour.

errorobjectOptional

Why the run failed. Present whenever status is failed.

metadatamap from strings to anyOptional

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error