Skip to the documentation
API

Start a one-off run

Hands the assistant one job to do in the background, with no task saved. Use it for work that takes too long to wait for in a chat.

POST/task-runs

Runs the real call on your workspace.

POST /task-runs

Hands the assistant one job to do in the background, with no task saved. Use it for work that takes too long to wait for in a chat.

Example

Needs what creating a task with the same toolkits would.

curl
curl -X POST "$OE/task-runs" -H "$AUTH" -H 'content-type: application/json' -d '{  "instruction": "Find every invoice we received in September and list the sender, the amount and the due date.",  "autonomy": "ask",  "maxSteps": 40}'
Response
{  "object": "task_run",  "id": "run_9d3a7e1c5b2f48a60c7e1d3b",  "taskId": "tsk_4b9e2c7a1f3d86e05a9c2b7d",  "taskName": "Morning summary",  "trigger": "schedule",  "threadId": null,  "status": "waiting",  "instruction": "Go through the mail that arrived since yesterday. Tell me which conversations need a reply from me, most urgent first, and draft a short reply for each.",  "autonomy": "organize",  "model": "standard",  "steps": 4,  "toolCalls": 6,  "actions": 1,  "result": null,  "error": null,  "errorDetail": null,  "pendingApprovals": 1,  "createdAt": "2026-10-13T07:00:04.112Z",  "startedAt": "2026-10-13T07:00:05.870Z",  "finishedAt": null,  "transcript": [    { "role": "user", "text": "Go through the mail that arrived since yesterday. …", "at": "2026-10-13T07:00:05.870Z", "calls": [] },    {      "role": "assistant",      "text": "",      "at": "2026-10-13T07:00:09.402Z",      "calls": [        { "id": "call_1", "tool": "listThreads", "args": { "folder": "inbox", "maxResults": 20 }, "done": true, "result": "…" }      ]    }  ],  "approvals": [{      "object": "task_approval",      "id": "apr_2f8c1a6e9b3d47c05e1a8f2c",      "runId": "run_9d3a7e1c5b2f48a60c7e1d3b",      "taskId": "tsk_4b9e2c7a1f3d86e05a9c2b7d",      "taskName": "Morning summary",      "tool": "replyToEmail",      "summary": "Reply to [email protected]: Re: Invoice 1042",      "args": {        "threadId": "thr_7c1e4a90",        "to": ["[email protected]"],        "subject": "Re: Invoice 1042",        "body": "Hi Ann, the invoice went out again this morning."      },      "status": "pending",      "createdAt": "2026-10-13T07:00:41.220Z",      "expiresAt": "2026-10-20T07:00:41.220Z",      "decidedAt": null    }]}

threadId hands the run one conversation as its starting point.

A workspace starts at most 100 one-off runs in 24 hours: 409 task_run_limit_reached.

The workspace owner and whoever started the run are notified when it waits for approval or fails.

Reference