# List or read Computers

URL: https://heaven.dev/docs/reference/computers/view
Updated: 2026-11-21

List accessible Computers or read a named Computer. A single Computer's result includes its state and any recent operations you can read. With list filters, follow the returned next cursor to read more matches.

`GET /v1/computer/`

## Parameters

- `computer` (string): Computer name or ID. Omit to list accessible Computers.
- `pattern` (string): Computer name filter, such as web-\*.
- `pool` (string): Only the Computers in this pool (name or ID).
- `tag` (string): Only the Computers with this tag.
- `states` (string[]): List Computers in any of the given states, such as running, stopped or failed.
- `shared` (boolean): Only include Computers others own that are shared with you for website or root access.
- `limit` (string): Maximum Computers per page in name order. MCP defaults to 100. Use the returned next value with `after` for more matches.
- `after` (string): Computer name to list after, in name order. Use the previous page's next value.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.
- `scope_pools` (string[]): Pool name or ID to include in a preview of an API key's resource scope. Combine with other scope filters to preview the union.
- `scope_computers` (string[]): Computer name or ID to include in a preview of an API key's resource scope.
- `scope_tags` (string[]): Tag whose Computers to include in a preview of an API key's resource scope.

## Returns

- `data` (object, always present): Accessible Computers, or one Computer with requested details and recent operations.
  - `alternative-1` (object): Computers you can access in the selected scope.
    - `computers` (object[] | null, always present): Visible Computers and their reported state, by name: a page of them when `limit` or `after` asks for one.
      - `items` (object): A Computer's identity, access and reported state.
        - `access` (string, always present): Your access role.
        - `commands` (string[]): Management commands permitted by your share. May be omitted.
        - `created_at` (string (date-time), always present): When the Computer was created.
        - `disk_used_bytes` (integer): Last measured disk use in bytes; absent if unknown. May be omitted.
        - `health` (object): Current access-health diagnosis, when available. May be omitted.
          - `detail` (string): An explanation of the access problem. May be omitted.
          - `reason` (string): A short explanation of the health state. May be omitted.
          - `ssh` (string): Reported SSH access health. May be omitted.
        - `id` (string, always present): Computer's stable ID.
        - `image` (string): Template image version. May be omitted.
        - `image_source` (object): Source registry image. May be omitted.
          - `auth_required` (boolean): Whether retrieving the image required registry credentials. May be omitted.
          - `automatic_disk` (boolean): Whether Heaven chose the disk size to fit the image. May be omitted.
          - `reference` (string, always present): Original registry image reference.
        - `name` (string, always present): Its current name.
        - `owner_email` (string): Owner's email for a shared Computer. May be omitted.
        - `pause_reason` (string): Why the Computer is paused. May be omitted.
        - `pool` (string, always present): Its pool's name.
        - `pool_id` (string, always present): Its pool's ID.
        - `sharing` (object): Sharing counts and website access for the owner. May be omitted.
          - `links` (integer, always present): Number of share links.
          - `people` (integer, always present): Number of people with sharing access.
          - `public` (boolean, always present): Whether the website is public.
          - `website_access` (string, always present): Website access level. Values: `"private"`, `"organization"`, `"public"`.
        - `size` (object, always present): Reported CPU, RAM and disk size.
          - `disk_bytes` (integer, always present): Logical disk size in bytes.
          - `memory_mib` (integer, always present): Memory size in mebibytes.
          - `vcpus` (integer, always present): Computer's vCPU count.
        - `ssh_dest` (string): SSH destination in `NAME@DOMAIN` form. May be omitted.
        - `state` (string, always present): State derived from requested changes and the latest observation. Values: `"checking"`, `"creating"`, `"degraded"`, `"deleting"`, `"failed"`, `"held"`, `"image_failed"`, `"moving"`, `"paused"`, `"preparing_image"`, `"resetting"`, `"restarting"`, `"running"`, `"starting"`, `"stopped"`, `"stopping"`, `"unknown"`.
        - `state_message` (string): State explanation and required action. May be omitted.
        - `tags` (string[]): Tags currently assigned to the Computer. May be omitted.
        - `url` (string): Main website URL. May be omitted.
        - `website_listening` (boolean): Whether the website port accepted a connection at the last check. Absent before a report. May be omitted.
    - `group` (string): Selected grouping for this list. May be omitted.
    - `next` (string): The `after` of the next page. Absent on the last page. May be omitted.
    - `total` (integer, always present): How many Computers the filters match, on every page.
  - `alternative-2` (object): A Computer's state, recent operations and requested details.
    - `access` (object): Sharing and website permissions. May be omitted.
      - `computer` (string, always present): Computer name.
      - `default_port` (integer, always present): Image's default website port. Zero means none is known.
      - `domains` (string[] | null, always present): Custom domain names assigned to this Computer.
      - `grants` (object[] | null, always present): People with access and how it was granted.
        - `items` (object): A person's access grant on a Computer.
          - `commands` (string[]): Additional management commands this grant permits. May be omitted.
          - `email` (string, always present): Recipient's email address.
          - `granted_at` (string (date-time), always present): When access was granted.
          - `granted_by` (string, always present): Person who granted access.
          - `link_id` (string): Share link that granted access, when applicable. May be omitted.
          - `name` (string): Recipient's display name, when set. May be omitted.
          - `notice` (string): Latest sharing email status. May be omitted.
          - `picture` (string): Recipient's profile picture URL. May be omitted.
          - `role` (string, always present): Access role. Root permits guest access; ownership is separate.
          - `user_id` (string, always present): Recipient's user ID.
          - `via` (string, always present): How this access was granted.
      - `invitations` (object[] | null, always present): Outstanding or recorded email invitations for this Computer.
        - `items` (object): An email invitation to access a Computer.
          - `commands` (string[] | null, always present): Additional commands the invitation grants.
          - `email` (string, always present): Invited email address.
          - `expires_at` (string (date-time), always present): When the invitation expires.
          - `id` (string, always present): Invitation ID.
          - `invited_at` (string (date-time), always present): When the invitation was sent.
          - `invited_by` (string, always present): Who sent the invitation.
          - `notice` (string | null, always present): Latest invitation email's state, or null without a recorded notice.
          - `role` (string, always present): Role granted when the invitation is accepted.
          - `state` (string, always present): Invitation's current state.
      - `links` (object[] | null, always present): Claimable share links and their current states.
        - `items` (object): A share link's metadata.
          - `created_at` (string (date-time), always present): When it was created.
          - `created_by` (string, always present): Who created the link.
          - `expires_at` (string (date-time) | null, always present): When it expires, or null without expiry.
          - `id` (string, always present): Link ID used for removal.
          - `label` (string, always present): Label identifying the link.
          - `max_uses` (integer | null, always present): Claim limit, or null without a limit.
          - `state` (string, always present): Whether the link is still claimable or has ended.
          - `uses` (integer, always present): Claims already made through the link.
      - `port` (integer, always present): Selected website guest port. Zero uses the image default.
      - `ports` (object[] | null, always present): Published public ports for the Computer.
        - `items` (object): A public port forwarding traffic to a Computer.
          - `address` (string, always present): Public connection address.
          - `computer_id` (string, always present): Computer ID.
          - `guest_port` (integer, always present): Destination port inside the Computer.
          - `name` (string, always present): Computer name.
          - `organization` (string): Computer's organization, when applicable. May be omitted.
          - `port` (integer, always present): Public port to connect to.
          - `published_at` (string (date-time), always present): When the port was published.
      - `public` (boolean, always present): Whether anyone can open the main website.
      - `support_root` (boolean, always present): Whether Heaven support has Root access.
      - `team_commands` (string[]): Additional commands granted to the whole organization. May be omitted.
      - `team_role` (string): Share role granted to the whole organization. May be omitted.
      - `teams` (object[] | null, always present): Shares granted to individual organization teams.
        - `items` (object): A Computer share granted to an organization team.
          - `commands` (string[] | null, always present): Additional commands granted to the team.
          - `granted_at` (string (date-time), always present): When the share was granted.
          - `granted_by` (string, always present): Who granted the share.
          - `role` (string, always present): Team's share role on this Computer.
          - `team` (string, always present): Recipient team's name.
      - `url` (string, always present): Its main website URL.
      - `website_access` (string, always present): Who can open the website: private grantees, the organization or the public. Values: `"private"`, `"organization"`, `"public"`.
    - `addresses` (object): Computer's address and route information. May be omitted.
      - `domains` (object[] | null, always present): Custom names served from their own ports.
        - `items` (object): A custom name served from its own guest port.
          - `name` (string, always present): Domain name.
          - `port` (integer, always present): Destination guest port.
      - `manager` (object, always present): Who manages these addresses.
        - `name` (string, always present): Manager's name.
      - `ports` (object[] | null, always present): Published public ports.
        - `items` (object): A public port forwarding to the Computer.
          - `address` (string, always present): Public address to connect to.
          - `guest_port` (integer, always present): Destination port inside the Computer.
          - `port` (integer, always present): Public port number.
      - `public_at` (string[] | null, always present): Public routes to this Computer through other Computers. Empty when its own website is public.
      - `range` (object, always present): Address pattern and port range for development websites.
        - `address` (string, always present): Development website address pattern.
        - `from` (integer, always present): First supported guest port.
        - `to` (integer, always present): Last supported guest port.
      - `website` (object, always present): Main website's address, access and last connection check.
        - `access` (string, always present): Who is permitted to open the website. Values: `"private"`, `"organization"`, `"public"`.
        - `address` (string, always present): Website's URL.
        - `listening` (boolean | null, always present): Whether the guest port accepted a connection at the last check. Null if unreported or the Computer is stopped.
        - `port` (integer, always present): Guest port served, or zero while none is known.
    - `computer` (object, always present): Computer's saved settings and latest observation.
      - `access` (string, always present): Your access role.
      - `account_id` (string, always present): Account that holds the Computer.
      - `commands` (string[]): Management commands permitted by your share. May be omitted.
      - `computer` (object, always present): Saved Computer identity and requested settings.
        - `comment` (string): Saved comment. May be omitted.
        - `created_at` (string (date-time), always present): When the Computer was created.
        - `desired_power` (string, always present): Requested power state, which can differ from the observed state. `frozen` means paused. Values: `"frozen"`, `"running"`, `"stopped"`.
        - `id` (string, always present): Stable Computer ID.
        - `image` (string, always present): Selected image version.
        - `image_digest` (string): Resolved immutable image digest, when available. May be omitted.
        - `image_source` (object): Original registry image reference, when applicable. May be omitted.
          - `auth_required` (boolean): Whether retrieving the image required registry credentials. May be omitted.
          - `automatic_disk` (boolean): Whether Heaven chose the disk size to fit the image. May be omitted.
          - `reference` (string, always present): Original registry image reference.
        - `lifecycle` (string, always present): Whether the Computer is active or being deleted. Values: `"active"`, `"deleting"`.
        - `login_user` (string, always present): User selected for guest login.
        - `name` (string, always present): Current Computer name.
        - `network` (object, always present): Computer's private network address.
          - `ipv4` (string, always present): Private IPv4 address.
        - `pool_id` (string, always present): Pool providing this Computer's capacity.
        - `root_volume` (object, always present): Disk's reported size.
          - `size_bytes` (integer, always present): Disk's logical size in bytes.
        - `shape` (object, always present): Saved CPU and memory settings.
          - `memory_mib` (integer, always present): Memory size in mebibytes.
          - `vcpus` (integer, always present): Computer's vCPU count.
        - `tags` (string[]): Saved tags. May be omitted.
      - `disk` (object | null, always present): Last disk measurement, or null before a report.
        - `alternative-1` (object): The Computer's latest disk measurement.
          - `reported_at` (string (date-time)): When the disk was measured. May be omitted.
          - `size_bytes` (integer, always present): Logical disk size in bytes.
          - `snapshot_bytes` (integer): Storage used by this Computer's snapshots, in bytes. May be omitted.
          - `source` (string, always present): Measurement source: `guest`, `host` or `unknown`.
          - `used_bytes` (integer): Measured disk use in bytes, when available. May be omitted.
      - `endpoint_problem` (string): Why guest access is unavailable, when a problem is known. May be omitted.
      - `health` (object): Current guest-access diagnosis. May be omitted.
        - `detail` (string): An explanation of the access problem. May be omitted.
        - `reason` (string): A short explanation of the health state. May be omitted.
        - `ssh` (string): Reported SSH access health. May be omitted.
      - `observation_stale` (boolean, always present): Whether the observation is outdated.
      - `owner_email` (string): Owner's email, when visible. May be omitted.
      - `owner_id` (string, always present): Computer owner's ID.
      - `owner_name` (string): Who shared the Computer with you, by name: its owner's, or the owning team's or organization's. May be omitted.
      - `pause_reason` (string): Why the Computer is paused. May be omitted.
      - `pool_name` (string): Computer's pool name. May be omitted.
      - `received_at` (string | null, always present): When Heaven received that report, or null before one arrived.
      - `sharing` (object): Computer's sharing summary. May be omitted.
        - `links` (integer, always present): Number of share links.
        - `people` (integer, always present): Number of people with sharing access.
        - `public` (boolean, always present): Whether the website is public.
        - `website_access` (string, always present): Website access level. Values: `"private"`, `"organization"`, `"public"`.
      - `size` (object, always present): Reported CPU and memory size.
        - `memory_mib` (integer, always present): Memory size in mebibytes.
        - `vcpus` (integer, always present): Computer's vCPU count.
      - `ssh_dest` (string): SSH destination in `NAME@DOMAIN` form. May be omitted.
      - `ssh_host` (string): SSH gateway hostname. May be omitted.
      - `ssh_user` (string): SSH gateway username selecting this Computer. May be omitted.
      - `state` (string, always present): State derived from saved changes and the latest observation. Values: `"checking"`, `"creating"`, `"degraded"`, `"deleting"`, `"failed"`, `"held"`, `"image_failed"`, `"moving"`, `"paused"`, `"preparing_image"`, `"resetting"`, `"restarting"`, `"running"`, `"starting"`, `"stopped"`, `"stopping"`, `"unknown"`.
      - `state_message` (string, always present): State explanation and required action.
      - `status` (object | null, always present): Latest boot and guest report, or null before a report.
        - `alternative-1` (object): The Computer's latest boot and guest report.
          - `boot_started_at` (string (date-time)): When the reported boot began. May be omitted.
          - `guest` (object): Latest report from inside the Computer. May be omitted.
            - `endpoint_reason` (string): Why the guest endpoint cannot currently accept access. May be omitted.
            - `init_error` (string): A reported initialization failure. May be omitted.
            - `kernel` (string, always present): Running guest kernel version.
            - `reported_at` (string (date-time), always present): When the guest made this report.
            - `root_bytes` (integer): Reported root filesystem size in bytes. May be omitted.
            - `root_grown_bytes` (integer): Disk size the root filesystem last grew to, in bytes. May be omitted.
            - `root_growth_error` (string): Why a requested filesystem increase could not be applied. May be omitted.
            - `root_used_bytes` (integer): Reported root filesystem use in bytes. May be omitted.
            - `setup_error` (string): A reported setup-script failure. May be omitted.
            - `setup_running` (boolean): Whether the setup script is still running. May be omitted.
            - `status` (string): Guest platform's reported state. May be omitted.
          - `image` (object): Image preparation details and errors. May be omitted.
            - `default_port` (integer): Website port exposed by the image. May be omitted.
            - `error_code` (string): Why image preparation failed, when a failure was recorded. May be omitted.
            - `login_user` (string): Image's guest login user. May be omitted.
            - `rootfs_bytes` (integer): Prepared image filesystem's size in bytes. May be omitted.
          - `image_progress` (object): Image download or preparation progress. May be omitted.
            - `download_bytes` (integer): Total download bytes when known. May be omitted.
            - `downloaded_bytes` (integer): Image bytes downloaded so far. May be omitted.
            - `stage` (string, always present): Whether preparation is waiting, downloading or building. Values: `"building"`, `"downloading"`, `"waiting"`.
            - `unpacked_bytes` (integer): Image bytes unpacked so far. May be omitted.
          - `last_exit` (object): How and when the Computer last stopped. May be omitted.
            - `at` (string (date-time), always present): When the exit occurred.
            - `kind` (string, always present): Reported exit cause, such as shutdown, reboot or crash. Values: `"crashed"`, `"destroyed"`, `"failed"`, `"reboot"`, `"shutdown"`, `"unknown"`.
          - `platform_ready_at` (string (date-time)): When the guest platform reported readiness for this boot. May be omitted.
          - `restart_required` (boolean): Whether a restart is required to finish applying a change. May be omitted.
          - `restart_to_update` (boolean): Whether restarting would apply a newer platform boot version. May be omitted.
          - `updated_at` (string (date-time), always present): When this observation was updated.
      - `support_root` (boolean, always present): Whether Heaven support has Root access to this Computer.
      - `url` (string): Computer's main website URL. May be omitted.
      - `usage` (object | null, always present): Latest usage measurements; null before a report.
        - `alternative-1` (object): The latest usage observation.
          - `memory_bytes` (integer): Memory attributed to this Computer, in bytes. May be omitted.
          - `observed_at` (string (date-time)): When usage was measured. May be omitted.
          - `rates` (object): CPU use over the sample interval. May be omitted.
            - `cpu_cores` (number, always present): Average number of vCPUs in use during the interval.
            - `window_seconds` (number, always present): Measurement interval in seconds.
          - `state` (string, always present): Measurement availability: `observed` for a valid sample, `unknown` or `not_sampled` otherwise.
      - `website` (object): Last connection check of the website's port. May be omitted.
        - `listening` (boolean, always present): Whether the website port accepted a connection.
    - `domains` (object[]): Custom names assigned to the Computer. May be omitted.
      - `items` (object): A Computer's domain name and its DNS and certificate status.
        - `added_at` (string (date-time), always present): When the name was assigned.
        - `certificate_state` (string): HTTPS certificate's current state, when applicable. May be omitted.
        - `computer` (string, always present): Destination Computer's name.
        - `computer_id` (string, always present): Destination Computer's ID.
        - `dns_checked_at` (string (date-time) | null, always present): When DNS was last checked.
        - `dns_failing_since` (string (date-time) | null, always present): When the current DNS failure began.
        - `dns_message` (string | null, always present): An explanation of the DNS problem, when present.
        - `dns_reason` (string | null, always present): DNS problem code, or null without a recorded problem.
        - `dns_state` (string, always present): Latest DNS-check state.
        - `domain` (string, always present): Registrable domain containing this name.
        - `maintenance_paused` (boolean, always present): Whether automatic domain maintenance is paused.
        - `name` (string, always present): Full domain name.
        - `paths` (object[] | null, always present): Path-specific routes to other Computers.
          - `items` (object): A path under a domain name routed to a Computer.
            - `computer` (string, always present): Destination Computer's name.
            - `computer_id` (string, always present): Destination Computer's ID.
            - `path` (string, always present): URL path prefix to match.
            - `port` (integer): Destination port when explicitly selected. May be omitted.
            - `strip_prefix` (boolean): Whether forwarding removes the matched prefix. May be omitted.
        - `port` (integer | null, always present): Guest port; null uses the Computer's website setting.
        - `proxied` (boolean, always present): Whether Cloudflare's proxy sits in front of the name.
        - `redirect` (string, always present): Redirect destination, when this name redirects.
        - `unproven` (boolean, always present): Whether the name is still waiting for DNS proof.
        - `wildcard` (boolean, always present): Whether this is a wildcard name.
    - `mail` (object): Computer's mail settings. May be omitted.
      - `note` (string): Effects of disabling mail reception, returned for that change. May be omitted.
      - `receiving_enabled` (boolean, always present): Whether mail reception is enabled for this Computer.
      - `receiving_reason` (string): Why receiving is disabled or unavailable, when applicable. May be omitted.
      - `reply_policy` (string, always present): Permitted reply recipients. Values: `"all"`, `"known"`, `"none"`, `"owner"`.
      - `sending_suspended` (boolean, always present): Whether outgoing mail is suspended.
    - `operations` (object[] | null, always present): Recent operations you are permitted to read.
      - `items` (object): An accepted change to one Computer. Work continues after the request disconnects.
        - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
        - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
        - `computer_id` (string, always present): Computer's stable ID.
        - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
        - `error_code` (string): Recorded failure code. May be omitted.
        - `id` (string, always present): Operation ID for `operation view`.
        - `kind` (string, always present): Change being tracked.
        - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
        - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
    - `ports` (object): Published ports and retained port assignments. May be omitted.
      - `kept` (object[]): Recently released ports, included for Computer-specific reads. Adding the guest port again reclaims its public port. May be omitted.
        - `items` (object): A recently released public port retained for this Computer for 30 days.
          - `address` (string, always present): Address it would be published on now.
          - `guest_port` (integer, always present): Guest port to add again to reclaim this public port.
          - `port` (integer, always present): Retained public port number.
          - `released_at` (string (date-time), always present): When the port was released.
      - `pools` (object[] | null, always present): Port availability and usage for each selected pool.
        - `items` (object): A pool's public-port usage and availability.
          - `allowed` (integer, always present): Applicable public-port allowance.
          - `held` (integer, always present): Public ports held by this pool's Computers.
          - `id` (string, always present): Pool ID.
          - `name` (string, always present): Pool name.
          - `new_left` (integer, always present): New ports available within the rolling 24-hour limit. Reclaimed ports are excluded.
          - `new_next_at` (string (date-time)): When the new-port allowance next increases. May be omitted.
          - `offered` (boolean, always present): Whether the pool has an address on which ports can be published.
          - `organization` (string): Owning organization. May be omitted.
          - `reason` (string): Why publishing is unavailable. May be omitted.
          - `shared` (boolean): Whether pools in the same account and placement share this allowance. May be omitted.
          - `shared_held` (integer): Ports held across that shared allowance. May be omitted.
      - `ports` (object[] | null, always present): Currently published ports.
        - `items` (object): A public port forwarding traffic to a Computer.
          - `address` (string, always present): Public connection address.
          - `computer_id` (string, always present): Computer ID.
          - `guest_port` (integer, always present): Destination port inside the Computer.
          - `name` (string, always present): Computer name.
          - `organization` (string): Computer's organization, when applicable. May be omitted.
          - `port` (integer, always present): Public port to connect to.
          - `published_at` (string (date-time), always present): When the port was published.
    - `snapshots` (object): Snapshots of the Computer's disk. May be omitted.
      - `computers` (object[] | null, always present): Storage that deleting each Computer's snapshots would free: on a page, the Computers of its snapshots.
        - `items` (object): Storage recoverable by deleting a Computer's snapshots together.
          - `id` (string, always present): Computer ID.
          - `name` (string, always present): Computer name.
          - `snapshot_bytes` (string | null, always present): Bytes freed by deleting all this Computer's snapshots, as a decimal string; null if unknown.
      - `next` (string): The `after` of the next page. Absent on the last page. May be omitted.
      - `observed_at` (string (date-time) | null, always present): Time of the storage observation, or null when unknown.
      - `pools` (object[] | null, always present): Storage use in the pools you can read.
        - `items` (object): A pool's included and used storage. Byte counts are decimal strings; null measurements are unknown.
          - `allowance_bytes` (string | null, always present): Included storage for files and snapshots, in bytes.
          - `files_bytes` (string | null, always present): Storage used by files, in bytes.
          - `id` (string, always present): Pool ID.
          - `snapshot_bytes` (string | null, always present): Storage used by snapshots, in bytes.
          - `used_bytes` (string | null, always present): Files and snapshots together, in bytes.
      - `snapshots` (object[] | null, always present): Snapshots matching the request.
        - `items` (object): A point-in-time disk snapshot. Byte counts are decimal strings; null measurements are unknown.
          - `automatic` (boolean, always present): Whether Heaven created the snapshot automatically.
          - `changed_since_bytes` (string | null, always present): Bytes changed since this snapshot.
          - `computer` (object, always present): Computer whose disk was snapshotted.
            - `id` (string, always present): Referenced object's stable ID.
            - `name` (string, always present): Referenced object's name.
          - `copies` (object[] | null, always present): Accessible Computers originating from this snapshot, including those later reset or restored.
            - `items` (object): A Computer, pool or snapshot reference.
          - `created_by` (object, always present): Who requested the snapshot.
            - `email` (string | null, always present): Their email address, or null when none is available.
            - `user_id` (string, always present): Person's user ID.
          - `data_bytes` (string | null, always present): Reported snapshot data, in bytes.
          - `data_source` (string | null, always present): Where the data-size measurement came from.
          - `disk_bytes` (string | null, always present): Logical disk size at capture, in bytes.
          - `expires_at` (string (date-time) | null, always present): When the snapshot expires. Null keeps it until explicitly deleted.
          - `id` (string, always present): Snapshot ID.
          - `kept_by` (object[] | null, always present): Snapshots retaining this deleted snapshot. Null unless dependencies delay deletion.
            - `items` (object): A Computer, pool or snapshot reference.
          - `kept_by_computers` (object[] | null, always present): Accessible copied Computers whose disks still retain this deleted snapshot's data.
            - `items` (object): A Computer, pool or snapshot reference.
          - `kept_by_other_copies` (integer): Number of copied Computers you cannot access that retain this snapshot. May be omitted.
          - `name` (string, always present): Snapshot's name within its Computer.
          - `note` (string, always present): Saved note about this snapshot.
          - `observed_at` (string (date-time) | null, always present): Time the measurements were last reported.
          - `requested_at` (string (date-time), always present): When snapshot creation was requested.
          - `saved` (string | null, always present): Disk capture method: `stopped`, `flushed` or `unflushed`. Flushing does not guarantee application consistency. Null means capture is unreported.
          - `size_bytes` (string | null, always present): Storage unique to this snapshot, in bytes.
          - `state` (string, always present): Snapshot lifecycle state. `pending` awaits disk capture.
          - `taken_at` (string (date-time) | null, always present): When the disk snapshot was taken, or null before it has been reported.
      - `stale` (boolean, always present): Whether the measurements are too old to treat as current.
      - `total` (integer, always present): How many snapshots the list holds, on every page.
    - `unavailable` (string[]): Requested parts that could not be read. May be omitted.
    - `withheld` (string[]): Requested parts your credential or role cannot read. May be omitted.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- API key permission: `view`.

## Examples

```sh tab="heaven CLI"
heaven view [COMPUTER]
  [--pattern PATTERN]
  [--pool POOL]
  [--tag TAG]
  [--state on|off ...]
  [--shared]
  [--limit N]
  [--after AFTER]
  [--group GROUP]
  [-l]
  [--organization ORGANIZATION]
  [--scope-pool SCOPE-POOL ...]
  [--scope-computer SCOPE-COMPUTER ...]
  [--scope-tag SCOPE-TAG ...]
```

```sh tab="SSH"
ssh cli@heaven.dev view [COMPUTER]
  [--pattern PATTERN]
  [--pool POOL]
  [--tag TAG]
  [--state on|off ...]
  [--shared]
  [--limit N]
  [--after AFTER]
  [--group GROUP]
  [-l]
  [--organization ORGANIZATION]
  [--scope-pool SCOPE-POOL ...]
  [--scope-computer SCOPE-COMPUTER ...]
  [--scope-tag SCOPE-TAG ...]
```

```sh tab="cURL"
curl https://heaven.dev/v1/computer/ \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "view",
  "arguments": {  } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "computers": [
      {
        "access": "owner",
        "created_at": "2026-11-16T11:00:00Z",
        "health": {
          "ssh": "answering"
        },
        "id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
        "image": "2026.10.31-1",
        "name": "my-api",
        "pool": "web",
        "pool_id": "pool-72af6cc84286403e",
        "sharing": {
          "links": 0,
          "people": 0,
          "public": false,
          "website_access": "private"
        },
        "size": {
          "disk_bytes": 100000595968,
          "memory_mib": 7936,
          "vcpus": 2
        },
        "ssh_dest": "my-api@heaven.dev",
        "state": "running",
        "url": "https://my-api.heaven.dev"
      },
      {
        "access": "owner",
        "created_at": "2026-11-16T11:00:00Z",
        "health": {
          "ssh": "answering"
        },
        "id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
        "image": "2026.10.31-1",
        "name": "my-site",
        "pool": "web",
        "pool_id": "pool-72af6cc84286403e",
        "sharing": {
          "links": 0,
          "people": 0,
          "public": false,
          "website_access": "private"
        },
        "size": {
          "disk_bytes": 100000595968,
          "memory_mib": 7936,
          "vcpus": 2
        },
        "ssh_dest": "my-site@heaven.dev",
        "state": "running",
        "url": "https://my-site.heaven.dev"
      }
    ],
    "total": 2
  }
}
```
