Start an agent run | CloudRaker documentation

curl -X POST https://api.cloudraker.com/v1/agent-runs \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "agent": "agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "files": [
    {
      "url": "https://documents.example.com/case123/intake_form.pdf"
    }
  ]
}'

{
  "object": "agent_run",
  "id": "agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "agent": {
    "id": "agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
    "name": "Document Review Agent",
    "version": 2.3
  },
  "status": "queued",
  "progress": {
    "tasks": {
      "total": 5,
      "completed": 1
    }
  },
  "tasks": [
    {
      "id": "task_01JQ8ZKMRT4V6WXYZ0TASK0001",
      "title": "Extract text from intake form",
      "executor": "agent",
      "status": "completed",
      "summary": "Text extraction completed successfully",
      "completedAt": "2024-06-10T14:22:00Z",
      "note": "OCR accuracy at 98%"
    }
  ],
  "statusUrl": "https://api.cloudraker.com/v1/agent-runs/agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH/status",
  "createdAt": "2024-06-10T14:20:00Z",
  "expiresAt": "2024-06-17T14:20:00Z",
  "finishedAt": "",
  "waiting": {
    "approvals": 2,
    "tasks": 3,
    "summary": "Awaiting human approval on extracted data"
  },
  "paused": {
    "reason": "model_error"
  },
  "approvals": [
    {
      "id": "approval_01JQ8ZKMRT4V6WXYZ0APPROVAL01",
      "kind": "before",
      "action": "approve_extracted_text",
      "requestedAt": "2024-06-10T14:25:00Z",
      "files": [
        {
          "id": "file_01JQ8ZKMRT4V6WXYZ0FILE0001",
          "name": "intake_form.pdf"
        }
      ],
      "rationale": "Verify accuracy of extracted text before proceeding",
      "params": {}
    }
  ],
  "incomplete": true,
  "result": "Extraction completed; awaiting approvals to continue.",
  "output": {
    "files": [
      {
        "id": "file_01JQ8ZKMRT4V6WXYZ0OUTPUT0001",
        "name": "extracted_text.json",
        "url": "https://api.cloudraker.com/files/file_01JQ8ZKMRT4V6WXYZ0OUTPUT0001/download?token=abc123"
      }
    ]
  },
  "error": {
    "code": "",
    "message": ""
  },
  "metadata": {}
}

Starts an agent on a set of files and returns the run.

1 {
2   "agent": "01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
3   "files": [{ "url": "https://example.com/intake.pdf" }],
4   "metadata": { "caseId": "42" }
5 }

Files take the usual two shapes: { "url": "…" } registers the file and fetches it, { "id": "…" } reuses one you already registered with POST /v1/files. Files you pass by URL join your reusable corpus, so a long-running agent never loses its inputs.

Waiting for the result. The call holds open up to ?wait= seconds (default 60, max 120, 0 returns immediately) and releases early the moment the run either finishes or blocks on a person.

Outcome	Response
Finished inside the window	`200` with the full run
Files still being prepared	`202` with `status: "queued"`
Still working at the cap	`202` with `{object, id, status, statusUrl}`
Blocked on a person	`202` right away, `status: "waiting"`

The 202 is a graceful degrade, never an error — poll the run; the run id is yours from this response on either way.

A queued run is not working yet: its files are still being prepared, which for scanned documents or long audio can take minutes, and reading the run is what picks it up once they are ready. So a queued run has to be polled — waiting on a webhook instead leaves it queued, because a run that has not started has nothing to report. Once it is running, its events are delivered as they happen.

Agent runs are long-lived: one blocked on a person waits days, up to the expiresAt on the run (about seven days), after which an unfinished run parks itself for good. Its files, and anything it already filed, are never taken back. Replaying an idempotency-key returns the original run alongside an idempotent-replay: true response header.

Learn more: Agents guide

Starts an [agent](https://docs.cloudraker.com/api/cloud-raker-api/agents/get-agent) on a set of files and returns the run. ```json { "agent": "01JQ8ZKMRT4V6WXYZ0ABCDEFGH", "files": [{ "url": "https://example.com/intake.pdf" }], "metadata": { "caseId": "42" } } ``` **Files** take the usual two shapes: `{ "url": "…" }` registers the file and fetches it, `{ "id": "…" }` reuses one you already registered with [POST /v1/files](https://docs.cloudraker.com/api/cloud-raker-api/files/create-file). Files you pass by URL join your reusable corpus, so a long-running agent never loses its inputs. **Waiting for the result.** The call holds open up to `?wait=` seconds (default `60`, max `120`, `0` returns immediately) and releases early the moment the run either finishes or blocks on a person. | Outcome | Response | | --- | --- | | Finished inside the window | `200` with the full run | | Files still being prepared | `202` with `status: "queued"` | | Still working at the cap | `202` with `{object, id, status, statusUrl}` | | Blocked on a person | `202` right away, `status: "waiting"` | <Note> The `202` is a graceful degrade, never an error — poll [the run](https://docs.cloudraker.com/api/cloud-raker-api/agents/get-agent-run); the run id is yours from this response on either way. A `queued` run is not working yet: its files are still being prepared, which for scanned documents or long audio can take minutes, and **reading the run is what picks it up** once they are ready. So a `queued` run has to be polled — waiting on a webhook instead leaves it queued, because a run that has not started has nothing to report. Once it is running, its events are delivered as they happen. Agent runs are long-lived: one blocked on a person waits days, up to the `expiresAt` on the run (about seven days), after which an unfinished run parks itself for good. Its files, and anything it already filed, are never taken back. Replaying an `idempotency-key` returns the original run alongside an `idempotent-replay: true` response header. </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.

Query parameters

waitintegerOptional0-120Defaults to 60

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.

Request

This endpoint expects an object.

agentstringRequired>=1 character

The agent to run, by id.

fileslist of objectsRequired

The files the agent works on, up to 200.

metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

webhookobjectOptional

Where to deliver this run’s events, given one of two ways.

{ "url": "…" } — a one-off https endpoint for this run only.
{ "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

Response

The finished 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

400

Bad Request Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

Starts an agent on a set of files and returns the run.

1 {
2   "agent": "01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
3   "files": [{ "url": "https://example.com/intake.pdf" }],
4   "metadata": { "caseId": "42" }
5 }

Waiting for the result. The call holds open up to ?wait= seconds (default 60, max 120, 0 returns immediately) and releases early the moment the run either finishes or blocks on a person.

Outcome	Response
Finished inside the window	`200` with the full run
Files still being prepared	`202` with `status: "queued"`
Still working at the cap	`202` with `{object, id, status, statusUrl}`
Blocked on a person	`202` right away, `status: "waiting"`

The 202 is a graceful degrade, never an error — poll the run; the run id is yours from this response on either way.

Learn more: Agents guide

1	{
2	"agent": "01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
3	"files": [{ "url": "https://example.com/intake.pdf" }],
4	"metadata": { "caseId": "42" }
5	}