# Usage and limits

> Read tenant usage and plan requests around the shared limits.

Pantheon is free during the builder preview; per-tenant rate limits apply, and billing is not planned yet.

## Read usage

Call `GET` `/v1/usage` with a tenant key carrying `usage:read`.

Tenant keys receive this scope by default. A signed-in dashboard session token also works.

The response covers only your tenant. Omit the dates for the last 30 days, including today.

Set `from` and `to` to inclusive UTC dates. The maximum range is 92 days.

```bash title="Terminal"
curl -sS --get "$PANTHEON_BASE_URL/v1/usage" \
  -H "Authorization: Bearer $PANTHEON_API_KEY" \
  --data-urlencode "from=2026-09-06" \
  --data-urlencode "to=2026-09-06"
```

```json title="Example JSON response"
{
  "sandbox_seconds_estimated": false,
  "from": "2026-09-06",
  "to": "2026-09-06",
  "totals": {
    "sessions_created": 2,
    "runs_total": 3,
    "input_tokens": 1200,
    "output_tokens": 450,
    "sandbox_seconds": 180.0,
    "tool_calls": 2,
    "runs_by_status": {
      "completed": 2,
      "failed": 1
    }
  },
  "daily": [
    {
      "date": "2026-09-06",
      "sessions_created": 2,
      "runs_total": 3,
      "input_tokens": 1200,
      "output_tokens": 450,
      "sandbox_seconds": 180.0,
      "tool_calls": 2
    }
  ]
}
```

| Value                           | Meaning                                                  |
| ------------------------------- | -------------------------------------------------------- |
| `from`, `to`                    | Inclusive UTC dates for the report.                      |
| `totals`                        | Combined metrics across the selected dates.              |
| `totals.runs_by_status`         | Run counts keyed by status.                              |
| `daily`                         | One row per UTC date, including days with zero usage.    |
| `sessions_created`              | Sessions created during the period.                      |
| `runs_total`                    | Runs created during the period.                          |
| `input_tokens`, `output_tokens` | Recorded tokens for those runs.                          |
| `sandbox_seconds`               | Sandbox lifetime within the selected period, in seconds. |
| `tool_calls`                    | Number of tool.started events.                           |
| `sandbox_seconds_estimated`     | True when sandbox time includes an estimated end.        |

## Per-tenant limits

Requests from keys and dashboard sessions share the same tenant limits. Each limit has its own 60-second window.

| Value                 | Meaning                                      |
| --------------------- | -------------------------------------------- |
| `sessions_per_minute` | 30 session creation requests per 60 seconds. |
| `runs_per_minute`     | 60 run requests per 60 seconds.              |
| `events_per_minute`   | 120 event requests per 60 seconds.           |

Session creation uses `/v1/sessions`. Run creation uses `/v1/sessions/{id}/runs`.

Posting events uses `/v1/sessions/{id}/events`. Resume requests share the event limit.

Operations that resume execution also use the run limit.

HTTP 429 returns `RATE_LIMITED` with limit details and a `Retry-After` header.

Wait for the specified seconds before retrying. See [the error response](https://pantheon-todo.alethiconsulting.com/docs/errors#rate-limited).

Tenant overrides can change these defaults. Ask for a higher limit through [Support](https://pantheon-todo.alethiconsulting.com/docs/support#limits).

## Bami usage

Bami model calls are platform-paid. They are marked `assistant: true` and stay out of tenant totals, daily rows, and rate limits.

Labelled tenant tests remain tenant usage. They appear in this report and count toward tenant limits.

See [Bami](https://pantheon-todo.alethiconsulting.com/docs/bami#usage) for the split and the pre-test disclosure.

## Sandbox seconds

Time is summed across sandbox instances, including recorded earlier instances after recreation.

Each lifetime is clipped to your date range and split across UTC days. Concurrent sandbox lifetimes add together.

Open sandbox time counts up to now, subject to the observation cap below.

Missing or stopped resources use the provider end timestamp when available. Otherwise, Pantheon uses the observation time.

Unobserved open resources are capped at their last observation plus the configured provider idle timeout.

The Daytona default is 10 minutes to stop plus 5 minutes to delete.

Legacy records without an observation use the instance start. Estimated ends set `sandbox_seconds_estimated` to `true`.

## Pitfalls

> **Warning**
>
> - **Usage returns HTTP 422:** The date range must contain 1 to 92 inclusive UTC days. Correct the dates.
> - **Requests return HTTP 429:** Your tenant exhausted a shared limit. Wait for Retry-After before retrying.
> - **Sandbox seconds are estimated:** Read sandbox_seconds_estimated before using these totals for precise accounting.