# 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.

```bash
curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_…/computer/start \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{
  "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 [#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 [#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 [#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-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 [#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`    |
