> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.cloudraker.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server. # Get an agent run GET https://api.cloudraker.com/v1/agent-runs/{id} 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=` (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](https://docs.cloudraker.com/capabilities/agents) Reference: https://docs.cloudraker.com/api/cloud-raker-api/agents/get-agent-run ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: CloudRaker API version: 1.0.0 paths: /v1/agent-runs/{id}: get: operationId: get-agent-run summary: Get an agent run description: >- 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=` (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](https://docs.cloudraker.com/capabilities/agents) tags: - agents parameters: - name: id in: path required: true schema: type: string - name: wait in: query description: >- 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. required: false schema: type: integer default: 0 - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: The run. content: application/json: schema: $ref: '#/components/schemas/V1AgentRun' '404': description: Unknown run id (or a run belonging to another organization). content: application/json: schema: description: Any type '429': description: >- Rate limited. The `/v1` API allows at least **67 requests per minute per organization** (about 1,000 requests per 15 minutes) — a guaranteed floor, enforced per edge location, so a geographically spread caller may get more. Wait for the `Retry-After` interval and retry — the error is `retryable`. content: application/json: schema: $ref: '#/components/schemas/GetAgentRunRequestTooManyRequestsError' servers: - url: https://api.cloudraker.com description: Production - url: https://api.staging.raker.one description: Staging - url: https://api.dev.raker.one description: Development components: schemas: V1AgentRunAgent: type: object properties: id: type: string name: type: string version: type: number format: double required: - id - name - version title: V1AgentRunAgent V1AgentRunStatus: type: string enum: - queued - processing - waiting - paused - completed - failed - cancelled - expired description: >- 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`. title: V1AgentRunStatus V1AgentRunWaiting: type: object properties: approvals: type: number format: double tasks: type: number format: double summary: type: string required: - approvals - tasks - summary description: What is blocking the run. Present while `status` is `waiting`. title: V1AgentRunWaiting V1AgentRunPausedReason: type: string enum: - model_error - system_error title: V1AgentRunPausedReason V1AgentRunPaused: type: object properties: reason: $ref: '#/components/schemas/V1AgentRunPausedReason' required: - reason description: >- Why the run parked. Present while `status` is `paused`. A paused run keeps everything it produced and can be started again. title: V1AgentRunPaused V1AgentRunProgressTasks: type: object properties: total: type: number format: double completed: type: number format: double required: - total - completed title: V1AgentRunProgressTasks V1AgentRunProgress: type: object properties: tasks: $ref: '#/components/schemas/V1AgentRunProgressTasks' required: - tasks title: V1AgentRunProgress V1AgentRunTaskExecutor: type: string enum: - agent - human description: >- Who performs the step: `agent` runs by itself, `human` waits for a person to complete it. title: V1AgentRunTaskExecutor V1AgentRunTaskStatus: type: string enum: - pending - ready - in_progress - completed - skipped description: >- Where this step stands. `pending` is blocked on its dependencies, `ready` is claimable, `skipped` satisfies anything waiting on it. title: V1AgentRunTaskStatus V1AgentRunTask: type: object properties: id: type: string title: type: string executor: $ref: '#/components/schemas/V1AgentRunTaskExecutor' description: >- Who performs the step: `agent` runs by itself, `human` waits for a person to complete it. status: $ref: '#/components/schemas/V1AgentRunTaskStatus' description: >- Where this step stands. `pending` is blocked on its dependencies, `ready` is claimable, `skipped` satisfies anything waiting on it. summary: type: - string - 'null' note: type: string completedAt: type: - string - 'null' required: - id - title - executor - status - summary - completedAt title: V1AgentRunTask V1AgentRunApprovalKind: type: string enum: - before - output title: V1AgentRunApprovalKind V1AgentRunApprovalFilesItems: type: object properties: id: type: string name: type: string required: - id - name title: V1AgentRunApprovalFilesItems V1AgentRunApproval: type: object properties: id: type: string kind: $ref: '#/components/schemas/V1AgentRunApprovalKind' action: type: string requestedAt: type: string rationale: type: - string - 'null' files: type: array items: $ref: '#/components/schemas/V1AgentRunApprovalFilesItems' params: type: object additionalProperties: description: Any type description: The inputs proposed for the step, for a `before` approval. required: - id - kind - action - requestedAt - files title: V1AgentRunApproval V1AgentRunOutputFilesItems: type: object properties: id: type: string name: type: string url: type: string required: - id - name title: V1AgentRunOutputFilesItems V1AgentRunOutput: type: object properties: files: type: array items: $ref: '#/components/schemas/V1AgentRunOutputFilesItems' required: - files description: >- Files attached to the run while its steps were completed, each with a signed download link valid for about an hour. title: V1AgentRunOutput V1AgentRunError: type: object properties: code: type: string message: type: string required: - code - message description: Why the run failed. Present whenever `status` is `failed`. title: V1AgentRunError V1AgentRun: type: object properties: object: type: string enum: - agent_run id: type: string agent: $ref: '#/components/schemas/V1AgentRunAgent' status: $ref: '#/components/schemas/V1AgentRunStatus' description: >- 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`. waiting: $ref: '#/components/schemas/V1AgentRunWaiting' description: What is blocking the run. Present while `status` is `waiting`. paused: $ref: '#/components/schemas/V1AgentRunPaused' description: >- Why the run parked. Present while `status` is `paused`. A paused run keeps everything it produced and can be started again. progress: $ref: '#/components/schemas/V1AgentRunProgress' tasks: type: array items: $ref: '#/components/schemas/V1AgentRunTask' approvals: type: array items: $ref: '#/components/schemas/V1AgentRunApproval' description: Sign-offs the run is waiting on, oldest first. incomplete: type: boolean description: >- Present and `true` on a `completed` run that still had outstanding work — read `tasks[]` to see what. result: type: string description: The agent's closing summary. output: $ref: '#/components/schemas/V1AgentRunOutput' description: >- Files attached to the run while its steps were completed, each with a signed download link valid for about an hour. error: $ref: '#/components/schemas/V1AgentRunError' description: Why the run failed. Present whenever `status` is `failed`. statusUrl: type: string metadata: type: object additionalProperties: description: Any type createdAt: type: string expiresAt: type: - string - 'null' description: >- 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. finishedAt: type: - string - 'null' required: - object - id - agent - status - progress - tasks - statusUrl - createdAt - expiresAt - finishedAt title: V1AgentRun V1AgentRunsIdGetResponsesContentApplicationJsonSchemaCode: type: string enum: - rate_limited title: V1AgentRunsIdGetResponsesContentApplicationJsonSchemaCode GetAgentRunRequestTooManyRequestsError: type: object properties: code: $ref: >- #/components/schemas/V1AgentRunsIdGetResponsesContentApplicationJsonSchemaCode message: type: string retryable: type: boolean requestId: type: string docUrl: type: string required: - code - message - retryable - requestId title: GetAgentRunRequestTooManyRequestsError securitySchemes: bearerAuth: type: http scheme: bearer ``` ## Examples **Request** ```json {} ``` **Response** ```json { "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" } } ``` **SDK Code** ```typescript import { CloudRakerClient } from "@cloudraker/api"; async function main() { const client = new CloudRakerClient({ token: "YOUR_TOKEN_HERE", }); await client.agents.getAgentRun("id", {}); } main(); ``` ```python from cloudraker import CloudRaker client = CloudRaker( token="YOUR_TOKEN_HERE", ) client.agents.get_agent_run( id="id", ) ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.cloudraker.com/v1/agent-runs/id" payload := strings.NewReader("{}") req, _ := http.NewRequest("GET", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.cloudraker.com/v1/agent-runs/id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.cloudraker.com/v1/agent-runs/id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('GET', 'https://api.cloudraker.com/v1/agent-runs/id', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.cloudraker.com/v1/agent-runs/id"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.cloudraker.com/v1/agent-runs/id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```