---
title: "Read Sandbox logs"
description: "Query current or retained workload and command output without starting compute."
---

> Documentation Index
> Fetch the complete documentation index at: https://boxcompute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Read Sandbox logs

Read logs for an owned Sandbox with the `sandbox:read` scope:

### TypeScript

```ts
const logs = await boxcompute.sandboxes.logs("sbx_REDACTED", {
  since: "2026-09-06T00:00:00Z",
  stream: "stderr",
  source: "process",
  limit: 100,
});
```
### Python

```python
logs = boxcompute.sandboxes.logs(
"sbx_REDACTED",
since="2026-09-06T00:00:00Z",
stream="stderr",
source="process",
limit=100,
)
```

The equivalent direct HTTP request is:

```bash
curl --get 'https://api.boxcompute.ai/api/v2/sandboxes/sbx_REDACTED/logs' \
  -H 'Authorization: Bearer bc_live_REDACTED' \
  --data-urlencode 'since=2026-09-06T00:00:00Z' \
  --data-urlencode 'stream=stderr' \
  --data-urlencode 'source=process' \
  --data-urlencode 'limit=100'
```

Log reads do not start stopped compute. Output remains queryable after compute becomes idle and stops, for as long as the provider retains it. Deleting the Sandbox removes the active instance, but retained logs can remain available through its read-only deletion record.

## Filters

| Query | Behavior |
| --- | --- |
| `since` | Inclusive RFC 3339 timestamp; defaults to Sandbox creation |
| `until` | Exclusive RFC 3339 timestamp; defaults to now and must be later than `since` |
| `stream` | `stdout` or `stderr` |
| `source` | `workload`, `execute`, or `process` |
| `limit` | 1–5,000 entries; defaults to 1,000 |

Results are ordered by timestamp. `workload` is Sandbox workload output, `execute` is synchronous command output, and `process` includes observable-operation output. Interactive shell transcripts are not included.

The response contains the customer-facing Sandbox ID, entries, a `truncated` flag, and `retention_seconds`:

```json
{
  "logs": {
"sandboxId": "sbx_REDACTED",
"entries": [
  {
    "timestamp": "2026-09-06T01:02:03.000Z",
    "stream": "stderr",
    "source": "process",
    "message": "database ready"
  }
],
"truncated": false,
"retention_seconds": 2592000
  }
}
```

If `truncated` is `true`, the result is incomplete. `retention_seconds` reports the configured
retention window—nominally 30 days today—but storage pressure can shorten availability, so retained
logs are not an archive.

## After deletion

First use `GET /api/v2/deleted-sandboxes` to find the deletion record. Read logs with that record's
`id` (`dsb_…`), not its original `sandboxId`:

```bash
curl --get 'https://api.boxcompute.ai/api/v2/deleted-sandboxes/dsb_REDACTED/logs' \
  -H 'Authorization: Bearer bc_live_REDACTED' \
  --data-urlencode 'source=process' \
  --data-urlencode 'limit=100'
```

This route accepts the same `since`, `until`, `stream`, `source`, and `limit` filters. It defaults to
the newest recorded runtime. To inspect an earlier one, pass an unchanged opaque value from the
record's `runtimes` array as `runtime`:

```bash
curl --get 'https://api.boxcompute.ai/api/v2/deleted-sandboxes/dsb_REDACTED/logs' \
  -H 'Authorization: Bearer bc_live_REDACTED' \
  --data-urlencode 'runtime=REDACTED_OPAQUE_RUNTIME'
```

The read does not restore, start or bill compute. Deletion history lasts about 15 months, but its
logs remain readable only while the log provider retains them—nominally about 30 days and
potentially less under storage pressure. Download anything you need before deletion; retained logs
are not a replacement for files or an archive. The current SDKs and CLI do not expose this route.

## Host CLI

The host-side BoxCompute CLI exposes the same query:

```bash
bxc sandbox logs SANDBOX_ID --source execute
bxc --json sandbox logs SANDBOX_ID \
  --since 2026-09-06T00:00:00Z --limit 100
```

CLI filters are:

- `--since` and `--until` for timestamps;
- `--stream` for `stdout` or `stderr`;
- `--source` for the output source; and
- `--limit` for the maximum entry count.

Without `--json`, the CLI prints entries to standard output and a count, retention value, and truncation indicator to standard error.

Source: https://boxcompute.ai/docs/logs/index.mdx