---
title: "List sandboxes for the caller's accessible projects"
method: GET
path: "/sandboxes"
tags: ["sandboxes"]
---

# List sandboxes for the caller's accessible projects

`GET /sandboxes`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/sandboxes`
- Auth: none declared

Each sandbox is one agent run, newest first. Filter by project, status, mission (`issueId`) or agent role. The filters apply before `limit`, so a page holds up to `limit` matching runs. When more runs match, `nextCursor` is set: send it back as `cursor`, with the same filters, for the next page.

## Query parameters

- `projectId` string
- `status` 'running' | 'stale' | 'completed' | 'stopped' | 'failed': How the agent's run in this sandbox stands. `running`: the agent works now. `completed`: the agent finished its work. `stopped`: something ended the run on purpose before it finished, for example a newer run, a stop of the mission or a person. `failed`: the agent reported a failure, or exited without a report. `stale`: the platform closed the run without a report, after its time limit or after a later attempt replaced it.
- `issueId` string: Only the runs of this mission, by its issue id (for example ENG-42).
- `role` 'planner' | 'builder' | 'reviewer' | 'qa': Only the runs of this agent role.
- `limit` integer
- `cursor` string: `nextCursor` from the previous page, with the same filters. Leave it out for the newest runs.

## Response `200`

Sandboxes

- ListSandboxesResponse
  - `data` SandboxInstance[], required
    - `sandboxId` string, required
    - `issueId` string, required
    - `projectId` string, nullable, required
    - `role` string, required
    - `harness` string, nullable, required
    - `harnessVersion` string, nullable, required
    - `runId` string, nullable, required
    - `status` 'running' | 'stale' | 'completed' | 'stopped' | 'failed', required: How the agent's run in this sandbox stands. `running`: the agent works now. `completed`: the agent finished its work. `stopped`: something ended the run on purpose before it finished, for example a newer run, a stop of the mission or a person. `failed`: the agent reported a failure, or exited without a report. `stale`: the platform closed the run without a report, after its time limit or after a later attempt replaced it.
    - `terminationReason` string, nullable, required
    - `instanceType` string, nullable, required
    - `createdAt` integer, required
    - `timeoutAt` integer, nullable, required
    - `lastHeartbeatAt` integer, nullable, required
    - `endedAt` integer, nullable, required: When the run ended, in epoch milliseconds. Null until the run ends.
    - `lastCpuPct` number, nullable, required
    - `lastMemUsedMb` integer, nullable, required
    - `lastMemTotalMb` integer, nullable, required
    - `lastDiskUsedPct` number, nullable, required
    - `lastMetricAt` integer, nullable, required
  - `nextCursor` string, nullable, required

## Other responses

- `400`: A cursor this API did not issue
- `401`: Unauthenticated

---

[API](https://skmtc.dev/letsship/apis/ship-api.md) · [All operations](https://skmtc.dev/letsship/apis/ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsship/apis/ship-api/revisions/e6eac1bcadd4?raw)