Operations
Follow a Cloud Computer start, stop, update or resize until it finishes.
Starting, stopping, updating or resizing an AI team's Cloud Computer takes from seconds to minutes.
These requests answer 202 Accepted with an operation, and you poll it until it is done.
curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_…/computer/start \
-H "Authorization: Bearer $HQ_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"{
"object": "operation",
"id": "op_…",
"kind": "computer.start",
"status": "running",
"target": { "type": "team", "id": "team_…" },
"requested": {},
"error": null,
"created_by": { "kind": "user_key", "key": "key_…", "label": "jean@example.com" },
"created_at": "2026-11-02T09:00:00Z",
"updated_at": "2026-11-02T09:00:00Z",
"completed_at": null
}Then GET /v1/operations/{operation_id}. While it runs, the answer carries Retry-After: 5: poll
no faster than that.
status | Meaning |
|---|---|
queued, running | Still going. |
succeeded | Done: the machine is running (start), stopped (stop), on the current system software (update) or on the new size (resize). |
failed | error.code and error.message say why, for example timeout (it did not finish within 30 minutes). |
canceled | Something else replaced it. |
GET /v1/operations lists the operations of the AI teams your key can see, newest first. An
operation is kept for 30 days.
One at a time per AI team
A team runs one operation at a time. Asking for another while one runs is refused with
409 operation_conflict, and operation names the one in progress so you can wait for it.
The same 409 operation_conflict answers while the machine is being changed from HQ (an update or
a resize someone started there, or a scheduled update); then there is no operation to name, so
retry after a minute.
A request that is refused (a permission, no Boost slot to assign, a conflict) creates no operation
and sends no operation.failed webhook.
Nothing to do
A start on a machine that is already running, or a resize to the size it already has, answers
200 with the Cloud Computer and no operation. So does an update that has nothing to start now
(the machine is current, or it is stopped and boots the current system software at its next
start); update_available on the Cloud Computer says whether an update is still pending.
Resizing to a smaller tier
Moving a running machine to a smaller tier does not interrupt it: the new size applies at its next
restart, as in HQ. The resize answers 200 with the Cloud Computer, tier set to the new tier and
change_pending: true, and no operation. To apply it now, send
POST /v1/teams/{team_id}/computer/update with {"restart": true}. A stopped machine gets the
new size when it next starts.
Stop and update refuse while sessions run
stop and update refuse with 409 computer_busy while sessions are running on the machine.
Send {"force": true} (stop) or {"restart": true} (update) to go ahead and stop them.
Who may
| Request | Permission |
|---|---|
| Start a sleeping machine | compute:wake |
| Start a stopped machine, stop, update | compute:rebuild |
| Resize | compute:resize |
| Unpause | compute:unpause |
| Read operations | compute:read |