List a Reason's computers

Lists the computers available to the caller for a Reason, with the same personal visibility, sharing and connected-computer selection rules as the app. Requires the opt-in computers:read scope. Returns 404 when the caller cannot start Sessions under this Reason. In the workspace resource model this includes eligible shared workspace cloud computers. Cloud live distinguishes awake from parked; connected state describes availability. Listing does not grant physical execution permission or wake computers.

_{Scope: computers:read}

GET /v3/organizations/{orgId}/reasons/{reasonId}/computers

List a Reason's computers

cURL

curl --request GET \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/reasons/{reasonId}/computers \
  --header 'Authorization: Bearer <token>'

200

{
  "computers": [
    {
      "id": "<string>",
      "name": "<string>",
      "kind": "cloud",
      "reason_id": "<string>",
      "size": "s",
      "os": "<string>",
      "state": "ready",
      "live": true,
      "unavailable_reason": "offline",
      "this_session": true,
      "sessions": [
        {
          "session_id": "<string>",
          "title": "<string>",
          "turn_running": true
        }
      ],
      "rcu_per_hour": "<string>",
      "keeps_processes": true,
      "previews_resume_on_wake": true,
      "keep_awake_until": "<string>",
      "yours": true,
      "owner": "<string>",
      "access": "personal",
      "is_origin_device": true,
      "roots": [
        {
          "id": "<string>",
          "label": "<string>",
          "repository": "<string>",
          "permissions": {
            "read": true,
            "write": true,
            "execute": true,
            "discover_environment": true,
            "expose_mcp": true
          },
          "direct_operations": [
            "fs.read"
          ],
          "process_limits": {},
          "browser_recording": {
            "available": true,
            "version": 1,
            "proof_ready": false,
            "pr_proof_guidance": "browser_recording is ordinary capture only; its proof_ready=false does not describe PR proof support. Check browser_pr_proof. For video, first use tools.pr.checkVideoAuth with an advertised browser_profile; use tools.pr.prepareProof for the advertised evidence format. Inventory does not establish authentication or verified evidence."
          },
          "browser_pr_proof": {
            "available": true,
            "version": 2,
            "image": true,
            "video": true,
            "profiles": [
              "<string>"
            ]
          }
        }
      ],
      "versions": {
        "latest_cli_versions": {
          "production": "<string>",
          "staging": "<string>"
        },
        "worker": {
          "running_version": "<string>",
          "installed_version": "<string>",
          "channel": "<string>",
          "observed_at": "<string>",
          "latest_published_version": "<string>",
          "comparison": "unknown"
        },
        "desktop": {
          "running_version": "<string>",
          "installed_version": "<string>",
          "channel": "<string>",
          "observed_at": "<string>",
          "latest_published_version": "<string>",
          "comparison": "unknown",
          "architecture": "arm64",
          "commit": "<string>",
          "started_at": "<string>"
        }
      },
      "desktop_available": true,
      "screen_lock": "locked"
    }
  ],
  "cloud_sizes": [
    {
      "size": "s",
      "memory_mb": 123,
      "vcpus": 123,
      "rcu_per_hour": "<string>"
    }
  ],
  "default_cloud_size": "s",
  "view_only_count": 1,
  "desktop_origin": {
    "status": "missing",
    "device_id": "<string>",
    "unavailable_reason": "<string>"
  },
  "machine_selection": {
    "source": "user",
    "target": {
      "kind": "cloud"
    }
  }
}

Authorizations

Authorization · string · header · required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Path Parameters

orgId · string · required

Organization id or slug. Resolve it with GET /v3/self.

reasonId · string<uuid> · required

The Reason id, returned as id by listReasons and createReason.

Response

200

application/json

The Reason's computer inventory for the caller.

Computers visible to the caller, with available cloud sizes. kind is cloud, mac, cli or worker. A cloud computer's state is ready whether awake or parked: live=true means awake, live=false means parked or not yet booted; busy means resizing. For connected computers, state=ready means available and state=offline means unavailable; live is always false. reason_id identifies a cloud computer's Reason; size is null for connected computers. Connected computers may include owner and yours. Session titles are included only for the caller's own Sessions. Listing never grants execution access or wakes a computer.

computers · object[] · required

Show child attributes

cloud_sizes · object[] · required

Show child attributes

default_cloud_size · enum<string> · required

Available options: s, m, l, xl

view_only_count · integer

Required range: x >= 0

desktop_origin · object

Show child attributes

machine_selection · object | null

Show child attributes