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.
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"{
"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.
Tenant overrides can change these defaults. Ask for a higher limit through Support.
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
- 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.