Get an agent run | CloudRaker documentation

{
  "object": "agent_run",
  "id": "agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "agent": {
    "id": "agent_12345",
    "name": "Data Processing Agent",
    "version": 2.3
  },
  "status": "waiting",
  "progress": {
    "tasks": {
      "total": 5,
      "completed": 3
    }
  },
  "tasks": [
    {
      "id": "task_001",
      "title": "Extract data from source",
      "executor": "agent",
      "status": "completed",
      "summary": "Data extraction completed successfully",
      "completedAt": "2024-06-10T09:15:00Z",
      "note": "No issues encountered"
    },
    {
      "id": "task_002",
      "title": "Review extracted data",
      "executor": "human",
      "status": "ready",
      "summary": null,
      "completedAt": null,
      "note": "Please verify data accuracy"
    }
  ],
  "statusUrl": "https://app.cloudraker.com/runs/agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH/status",
  "createdAt": "2024-06-10T09:00:00Z",
  "expiresAt": "2024-06-17T09:00:00Z",
  "finishedAt": null,
  "waiting": {
    "approvals": 2,
    "tasks": 1,
    "summary": "Waiting for user approval on data export"
  },
  "paused": {
    "reason": "model_error"
  },
  "approvals": [
    {
      "id": "approval_789",
      "kind": "before",
      "action": "Approve data export",
      "requestedAt": "2024-06-10T09:20:00Z",
      "files": [
        {
          "id": "file_456",
          "name": "extracted_data_preview.csv"
        }
      ],
      "rationale": "Ensure data compliance before export",
      "params": {
        "exportFormat": "CSV",
        "includeHeaders": true
      }
    }
  ],
  "incomplete": true,
  "result": "Data export paused awaiting approval",
  "output": {
    "files": [
      {
        "id": "file_123",
        "name": "partial_export_20240610.csv",
        "url": "https://files.cloudraker.com/download/file_123?token=abc123"
      }
    ]
  },
  "error": {
    "code": "none",
    "message": ""
  },
  "metadata": {
    "priority": "high",
    "requestedBy": "user_987"
  }
}

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.

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

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. **Long-polling.** `?wait=<seconds>` (0–120) holds the request until the run finishes or blocks on a person. <Note> 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. </Note> **Learn more:** [Agents guide](https://docs.cloudraker.com/capabilities/agents)

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

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

waitingobject

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

pausedobject

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

approvalslist of objects

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

incompleteboolean

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

resultstring

The agent's closing summary.

outputobject

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

errorobject

Why the run failed. Present whenever status is failed.

metadatamap from strings to any

Errors

404

Not Found Error

429

Too Many Requests Error

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.

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.

Learn more: Agents guide

$	curl https://api.cloudraker.com/v1/agent-runs/id \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json"