# Operations

Long-running changes to a Cloud Computer, and how they settled.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List operations [#list-operations]

    <ApiEndpointHeader method="GET" path="/v1/operations" scope="compute:read" />

    Newest first, on the AI teams the key's holder can see. Kept 30 days.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="team" type="string">
        Only operations on this AI team.
      </ApiParam>

      <ApiParam name="status" type="string">
        Only operations in this state. One of `running`, `succeeded`, `failed`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Operation](#operation) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of operations.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/operations \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/operations', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/operations",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "operation",
          "id": "op_pgDHKopuDeR6aX2GPYNtx5",
          "kind": "computer.resize",
          "status": "running",
          "target": {
            "type": "team",
            "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd"
          },
          "requested": {
            "tier": "boost"
          },
          "error": null,
          "created_by": {
            "kind": "service_key",
            "key": "key_ff7QejQ24AGmu5tv2IXIdw",
            "label": "CI deploy bot"
          },
          "created_at": "2026-10-14T16:10:00.000Z",
          "updated_at": "2026-10-14T16:10:04.000Z",
          "completed_at": null
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an operation [#get-an-operation]

    <ApiEndpointHeader method="GET" path="/v1/operations/{operation_id}" scope="compute:read" />

    Poll until `status` is `succeeded` or `failed`; `Retry-After` says when to ask again.

    <ApiParams title="Path parameters">
      <ApiParam name="operation_id" type="string" required="true">
        An operation id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Operation](#operation) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The operation.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/operations/op_pgDHKopuDeR6aX2GPYNtx5 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/operations/op_pgDHKopuDeR6aX2GPYNtx5', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/operations/op_pgDHKopuDeR6aX2GPYNtx5",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "operation",
      "id": "op_pgDHKopuDeR6aX2GPYNtx5",
      "kind": "computer.resize",
      "status": "running",
      "target": {
        "type": "team",
        "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd"
      },
      "requested": {
        "tier": "boost"
      },
      "error": null,
      "created_by": {
        "kind": "service_key",
        "key": "key_ff7QejQ24AGmu5tv2IXIdw",
        "label": "CI deploy bot"
      },
      "created_at": "2026-10-14T16:10:00.000Z",
      "updated_at": "2026-10-14T16:10:04.000Z",
      "completed_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Operation [#operation]

    A change the reconcilers carry out. It settles as succeeded or failed.

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="kind" type="string">
        Open-ended: computer.start, computer.stop, computer.update, computer.resize, webhook_endpoint.replay.
      </ApiParam>

      <ApiParam name="status" type="string">
        running, succeeded or failed.
      </ApiParam>

      <ApiParam name="target" type="object" />

      <ApiParam name="requested" type="object" />

      <ApiParam name="error" type="object or null" />

      <ApiParam name="created_by" type="object" />

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="updated_at" type="string (date-time)" />

      <ApiParam name="completed_at" type="string or null" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Operation object"
    {
      "object": "operation",
      "id": "op_pgDHKopuDeR6aX2GPYNtx5",
      "kind": "computer.resize",
      "status": "running",
      "target": {
        "type": "team",
        "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd"
      },
      "requested": {
        "tier": "boost"
      },
      "error": null,
      "created_by": {
        "kind": "service_key",
        "key": "key_ff7QejQ24AGmu5tv2IXIdw",
        "label": "CI deploy bot"
      },
      "created_at": "2026-10-14T16:10:00.000Z",
      "updated_at": "2026-10-14T16:10:04.000Z",
      "completed_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
