---
title: "Read a sandbox by id or name"
method: GET
path: "/api/v0beta1/rigs/{id}"
tags: ["Sandboxes"]
---

# Read a sandbox by id or name

`GET /api/v0beta1/rigs/{id}`

## Request

- Base URL: `https://app.amika.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://app.amika.dev/api/v0beta1/rigs/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `wos-session`

## Path parameters

- `id` string, required

## Query parameters

- `by` 'name' | 'id' | 'ref' | 'name_or_id': How to interpret the sandbox `{id}` path param: ref/name_or_id (default; matches an id or a name and rejects an ambiguous match with 409 `resource_ref_ambiguous`), name, or id.

## Response `200`

Sandbox with its guest DNS hostname.

- GetSandboxResponse
  - `id` string, required
  - `user_id` string, nullable, required
  - `org_id` string, required
  - `name` string, required
  - `provider` string, nullable, required
  - `provider_sandbox_id` string, nullable, required
  - `amika_opencode_web` string, nullable, required
  - `repo_name` string, nullable, required
  - `repo_provider` string, nullable, required
  - `repo_id` string, nullable, required
  - `repo_url` string, nullable, required
  - `branch` string, nullable, required
  - `commit_hash` string, nullable, required
  - `snapshot` string, nullable, required
  - `snapshot_name` string, nullable
  - `sandbox_preset` string, nullable
  - `sandbox_size` string, nullable
  - `sandbox_size_config` object, nullable
    - `name` string, nullable, required
    - `vcpus` number, required
    - `memoryGib` number, required
    - `diskGib` number, required
    - `diskGrowOnly` boolean, required
  - `github_auth_mode` 'pat' | 'app_token' | 'null', nullable
  - `github_credential_provisioned` boolean, nullable
  - `error_message` string, nullable
  - `current_session_id` string, nullable, required
  - `services` object[], nullable, required
    - `name` string, required
    - `url` string, required
    - `hostPort` integer, required
    - `containerPort` integer, required
    - `protocol` string, required
    - `kind` 'system' | 'user'
  - `state` string
  - `status` 'creating' | 'starting' | 'running' | 'stopping' | 'stopped' | 'suspending' | 'suspended' | 'snapshotting' | 'failed' | 'unknown'
  - `setup_status` 'ok' | 'setup-running' | 'git-failed' | 'setup-failed' | 'sys-setup-failed' | 'null', nullable
  - `live_state_pending` boolean
  - `urls_expire_at` union
    - string
    - string, date-time
    - unknown
  - `secret_names` string[]
  - `mounted_secrets` object[]
    - `name` string, required
    - `scope` 'user' | 'org', required
    - `managed` boolean, required
    - `credential_type` 'api_key' | 'oauth' | 'null', nullable, required
    - `provider` string, nullable, required
  - `resolved_agent_credentials` union[]
    - union
      - object
        - `kind` string, required
        - `outcome` 'resolved', required
        - `name` string, required
        - `type` 'oauth' | 'api_key', required
        - `source` string, required
      - object
        - `kind` string, required
        - `outcome` 'skipped', required
        - `reason` 'request:none' | 'no_user_credential', required
  - `agent_credentials` object[]
    - `kind` string, required
    - `name` string, nullable, required
    - `scope` 'user' | 'org' | 'null', nullable, required
    - `credential_type` 'api_key' | 'oauth' | 'null', nullable, required
    - `inject_target` string, nullable, required
  - `created_by` object, nullable
    - `name` string, nullable, required
    - `email` string, nullable, required
  - `agent_cwd` string, nullable
  - `ssh_key_status` 'ready' | 'no-key' | 'stale-keys' | 'unknown'
  - `origin` string, nullable
  - `host_id` string, nullable
  - `created_at` union, required
    - string
    - string, date-time
  - `updated_at` union, required
    - string
    - string, date-time
  - `hostname` string, required

## Other responses

- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Error
- `409`: Error

## Changes

- **2026-10-29** `86f031a957c1`: 1 info
  - added the optional property `allOf[#/components/schemas/Sandbox]/live_state_pending` to the response with the `200` status
- **2026-10-23** `c46868fd7b41`: 3 info
  - added the new optional `query` request parameter `by`
  - added the non-success response with the status `400`
  - added the non-success response with the status `409`
- **2026-10-03** `a122301d00e0`: 19 breaking, 21 warning, 1 info
  - the response's body type changed from `object` to no type for status `200`
  - removed the required property `amika_opencode_web` from the response with the `200` status
  - removed the required property `branch` from the response with the `200` status
  - removed the required property `commit_hash` from the response with the `200` status
  - …37 more
- **2026-09-30** `f9bd53246a8c`: 3 info
  - added the optional property `agent_credentials` to the response with the `200` status
  - added the optional property `host_id` to the response with the `200` status
  - added the optional property `sandbox_size_config` to the response with the `200` status
- **2026-09-21** `4d4f02352fdb`: 1 breaking, 1 info
  - removed the required property `provider_url` from the response with the `200` status
  - added the optional property `services/items/kind` to the response with the `200` status

[Operation history](https://skmtc.dev/amika/apis/amika-api/changes/api/v0beta1/rigs/:id/get.md)

---

[API](https://skmtc.dev/amika/apis/amika-api.md) - [All operations](https://skmtc.dev/amika/apis/amika-api/llms.txt) - [OpenAPI document](https://skmtc.dev/amika/apis/amika-api/revisions/86f031a957c1?raw)