Complete a human step

POST

/v1/agent-runs/:id/tasks/:taskId/complete

Marks one of the run’s executor: "human" steps done, which releases everything waiting on it.

1 { "note": "Client signed; scan attached.", "files": ["file_01JQ8ZKMRT4V6WXYZ0ABCDEF"] }

Both fields are optional. files are ids you registered or that the run already holds; they are attached to the step and show up in the run’s output.files.

Only human steps are completable — an agent’s own step answers 422. A step whose dependencies are unfinished answers 409, and so does one that is already done. The response carries the step plus run.status; ?wait= holds the request while the run picks the work back up.

An API key has no person behind it, so the run records your organization’s key as the actor rather than a named individual.

Learn more: Agents guide

Marks one of the run's `executor: "human"` steps done, which releases everything waiting on it. ```json { "note": "Client signed; scan attached.", "files": ["file_01JQ8ZKMRT4V6WXYZ0ABCDEF"] } ``` Both fields are optional. `files` are ids you [registered](https://docs.cloudraker.com/api/cloud-raker-api/files/create-file) or that the run already holds; they are attached to the step and show up in the run's `output.files`. Only human steps are completable — an agent's own step answers `422`. A step whose dependencies are unfinished answers `409`, and so does one that is already done. The response carries the step plus `run.status`; `?wait=` holds the request while the run picks the work back up. <Note> An API key has no person behind it, so the run records your organization's key as the actor rather than a named individual. </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

taskIdstringRequired>=1 character

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.

notestringOptional<=2000 characters

What you did, recorded on the step and visible on the run.

fileslist of stringsOptional

Files produced while doing the step, by file id.

Response

The completed step, and where the run stands after it.

object"agent_run_task"

idstring

titlestring

executorenum

Who performs the step: agent runs by itself, human waits for a person to complete it.

statusenum

summarystring or null

completedAtstring or null

runobject

notestring

Errors

400

Bad Request Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

$	curl -X POST https://api.cloudraker.com/v1/agent-runs/id/tasks/taskId/complete \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"object": "agent_run_task",
3	"id": "task_9f8b7c6d5e4a3b2c1d0e",
4	"title": "Review Contract Signature",
5	"executor": "human",
6	"status": "completed",
7	"summary": "Client has signed the contract and all documents are verified.",
8	"completedAt": "2024-06-10T15:45:00Z",
9	"run": {
10	"id": "run_123abc456def789ghi",
11	"status": "processing",
12	"statusUrl": "https://app.cloudraker.com/runs/run_123abc456def789ghi/status"
13	},
14	"note": "Client signed; scan attached."
15	}