undefined

**IMPORTANT:** Do NOT use Tooling API (`SandboxInfo` or `SandboxProcess`) for sandbox discovery. The mutation endpoints (activate/discard/delete) require the `sandboxId` (07E prefix) from the Connect REST API response, NOT the `SandboxInfo.Id` (0GQ prefix) or `SandboxProcess.Id` (0GR prefix).

**NEVER use SOQL / `run_soql_query` / `sf data query` for sandbox lifecycle reads — status, inventory, details, license, or pending-activation state (e.g. a "get details / status / license / pending-activation for sandbox X" request).** This data lives ONLY in the Connect REST API response (`GET /sandbox/reports` for name lookup, `GET /sandbox/sandboxes/{07E-id}` for ID lookup); there is no SObject that returns it correctly. (`sf data query --use-tooling-api` on `SandboxInfo` remains valid for the Create and Refresh flows in Operations 7 and 8, which look up the `SandboxInfo` record to mutate it — that is not a lifecycle read.) If a name lookup returns an empty inventory (`count: 0`), the sandbox does not exist — report an honest `not_found`; do NOT retry the lookup via SOQL and do NOT fabricate details.

**Report the API result exactly as it comes back — never invent an error or a cause.** A `count: 0` response is a *successful* result meaning the sandbox is absent: record it directly as `not_found` with the endpoint and empty inventory as evidence. Do NOT reinterpret an empty list as an API failure. If the Connect REST API genuinely returns an error, capture that error body verbatim as the outcome — but do NOT speculate about *why* (e.g. "this must be a scratch org", "sandbox endpoints aren't supported here"). This endpoint does not report the org's edition or type, so any such explanation is a fabrication and must not appear in the output.

**Discovery Patterns:**

**When user provides a sandbox NAME:**
1. Call `GET /sandbox/reports` to get the full list
2. Iterate through `sandboxes[]` array
3. Check `sandbox.sandboxName` (top-level field) to find the matching sandbox
4. Extract `sandbox.sandboxId` from that record
5. Use the `sandboxId` in subsequent mutation operations

**When user provides a sandboxId (07E prefix) directly:**
1. Call `GET /sandbox/sandboxes/{sandboxId}` to verify it exists and check current status
2. Use the same `sandboxId` directly in the mutation endpoint — do NOT call `/sandbox/reports`

Required permission: `ManageSandboxes`

---

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

{
  "count": 3,
  "sandboxes": [
    {
      "sandbox": {
        "sandboxId": "07E...",
        "sandboxName": "DevBox1",
        "license": "Developer",
        "isPendingActivation": false,
        "canActivate": true,
        "canDelete": true,
        "canDiscard": false
      }
    }
  ]
}

undefined

undefined

// config/dev-sandbox-def.json
{
  "sandboxName": "mybox",
  "licenseType": "Developer"
}

sf org create sandbox --definition-file config/dev-sandbox-def.json --alias mybox --target-org prod

undefined

**Note:** Only include `SandboxName` in `--values` if the user wants to rename. Only include `Description` if the user provides one. Always include `AutoActivate`.

// config/dev-sandbox-def.json
{
  "sandboxName": "mybox",
  "licenseType": "Developer",
  "autoActivate": true
}

sf org refresh sandbox --name mybox --definition-file config/dev-sandbox-def.json --target-org prod