> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplismart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Analytics Commands
> CLI commands for monitoring usage and cost on the Simplismart platform
Fetch time-series usage and cost data from the command line using `simplismart usage`.
## Cost & Usage
### Usage Stats
Fetches cost and compute usage for a given plan type and time range.
```bash theme={null}
simplismart usage stats [options]
```
| Option | Description |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--plan-type TYPE` | Compute plan to query (required). See [Plan Types](#plan-types) |
| `--start-time TIME` | Range start in ISO 8601 format (required) |
| `--end-time TIME` | Range end in ISO 8601 format (required) |
| `--window-size SIZE` | Aggregation bucket size (required). Options are: `MINUTE`, `15MIN`, `30MIN`, `HOUR`, `3HOUR`, `6HOUR`, `12HOUR`, `DAY`, `WEEK` |
| `--workspace-id UUID` | Restrict to a specific workspace UUID (uses org default if omitted) |
| `--deployment-id a,b,...` | Filter by deployment UUID(s). Only valid for `private`, `byoc` |
| `--deployment-slug a,b,...` | Filter by deployment slug(s). Only valid for `private`, `byoc` |
| `--model-name a,b,...` | Filter by model name(s) (e.g. `DeepSeek-R1`). Only valid for `shared` |
| `--training-job-id a,b,...` | Filter by training job UUID(s). Only valid for `training` |
| `--training-job-name a,b,...` | Filter by training job name(s). Only valid for `training` |
| `--model-repo-id a,b,...` | Filter by model repo UUID(s). Only valid for `compilation` |
| `--model-repo-name a,b,...` | Filter by model repo name(s). Only valid for `compilation` |
| `--include-all-statuses` | Include all deployment statuses (SUCCESS, STOPPED, DELETED, FAILED, etc.). Default: only SUCCESS and STOPPED. Not supported for `training` |
| `--group-by deployment\|accelerator` | `accelerator` pools items per GPU/CPU type instead of per deployment — the same toggle as the dashboard's Group By dropdown. Only valid for `--plan-type` in `private`/`reserved`. For `--plan-type reserved`, the pooled reservation commitment breakdown and commitment-adjusted `total_cost` are always included regardless of this choice — there's no separate flag to request them |
Each filter flag can be passed only once (use comma-separated values like `a,b,c` for multiple values). Passing an unsupported filter for the selected plan type returns an error.
1. You can find `workspace-id` under Settings > Workspaces. Select your workspace and copy the workspace ID.
2. Go to Deployments and select a deployment to find the `deployment-id` and `deployment-slug`.
#### Plan Types
| Value | Description |
| ------------- | --------------------------------------- |
| `shared` | Shared endpoint usage |
| `private` | Private dedicated deployment usage |
| `byoc` | Bring Your Own Compute deployment usage |
| `reserved` | Reserved capacity usage |
| `training` | Training and fine-tuning job usage |
| `compilation` | Model compilation job usage |
**Examples:**
**Dedicated usage (`private`): daily cost for the last 7 days**
```bash theme={null}
simplismart usage stats \
--plan-type private \
--start-time 2026-04-28T00:00:00+00:00 \
--end-time 2026-05-05T00:00:00+00:00 \
--window-size DAY
```
**Shared endpoint usage (`shared`): hourly cost for the last 24 hours, linked to a given workspace**
```bash theme={null}
simplismart usage stats \
--plan-type shared \
--start-time 2026-05-04T00:00:00+00:00 \
--end-time 2026-05-05T00:00:00+00:00 \
--window-size HOUR \
--workspace-id
```
**Dedicated/BYOC usage (`private`): daily cost scoped to deployments by `--deployment-id` (comma-separated UUIDs)**
```bash theme={null}
simplismart usage stats \
--plan-type private \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY \
--deployment-id ,
```
**Shared usage (`shared`): daily cost filtered to inference on specific `--model-name` values**
```bash theme={null}
simplismart usage stats \
--plan-type shared \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY \
--model-name DeepSeek-R1,Llama-3
```
**Training (`training`): weekly rollup for specific jobs (`--training-job-name`)**
```bash theme={null}
simplismart usage stats \
--plan-type training \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size WEEK \
--training-job-name finetune-llama-v1,finetune-llama-v2
```
**Compilation (`compilation`): weekly rollup for `--model-repo-name`:**
```bash theme={null}
simplismart usage stats \
--plan-type compilation \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size WEEK \
--model-repo-name my-model-repo
```
**Reserved (`reserved`): daily cost plus the pooled reservation commitment breakdown**
```bash theme={null}
simplismart usage stats \
--plan-type reserved \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY \
--group-by deployment | jq '.reservation_commitment'
```
For `--plan-type reserved`, this breakdown is always included — there's no flag to pass. `total_cost` reflects what your org is actually billed under the reservation, and the response gains a `reservation_commitment` array — one entry per committed GPU type, each with a `daily` list of `{timestamp, overage_amount, true_up_amount}`. `items` includes every deployment covered by the reservation, even ones that predate it.
With `--group-by accelerator` instead, use `items[].points[].computed_overage_amount` / `computed_true_up_amount` per time bucket rather than `reservation_commitment`:
```bash theme={null}
simplismart usage stats \
--plan-type reserved \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY \
--group-by accelerator | jq '.items[] | {event_name, points: [.points[] | {timestamp, computed_overage_amount, computed_true_up_amount}]}'
```
**Private/Reserved: pooled per-accelerator-type breakdown instead of per-deployment**
```bash theme={null}
simplismart usage stats \
--plan-type private \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY \
--group-by accelerator
```
`--group-by` just changes how `items` is organized — it's available for both `--plan-type private` and `--plan-type reserved`, with the same two values (`deployment` or `accelerator`) either way. The reservation breakdown above only ever comes with `--plan-type reserved` — a `--plan-type private` request, even with `--group-by accelerator`, never includes `reservation_commitment`. For `--plan-type reserved`, that breakdown is always included and always covers your whole account, regardless of which `--group-by` you pick.
Pooled (`--group-by accelerator`) items gain a `sources` key (a list of every deployment source folded into it) in place of a single `source` value. Each point in a pooled item also carries `computed_commitment_utilized_amount`, `computed_overage_amount`, and `computed_true_up_amount`:
```json theme={null}
{
"timestamp": "2026-07-14T00:00:00Z",
"usage": "21220.0",
"cost": "1448.7226666666668",
"event_count": 9401,
"computed_commitment_utilized_amount": "115.104",
"computed_overage_amount": "2.16",
"computed_true_up_amount": "204.29866666666666"
}
```
* **`computed_commitment_utilized_amount`** — cost covered by capacity you've already committed to.
* **`computed_overage_amount`** — cost billed at on-demand rates because usage went above your committed quantity that window.
* **`computed_true_up_amount`** — committed capacity you paid for but didn't use that window.
**Which field to use, by grouping:**
| `--group-by` | Use |
| ------------- | --------------------------------------------------------------------------------------- |
| `accelerator` | `items[].points[].computed_overage_amount` / `computed_true_up_amount`, per time bucket |
| `deployment` | `reservation_commitment[].daily[].overage_amount` / `true_up_amount`, account-wide |
**Expected output** — a single JSON object printed to stdout, with cost/usage broken down per `items` entry (one per deployment, or one per accelerator type with `--group-by accelerator`) and per time bucket within each entry's `points`:
```json theme={null}
{
"total_cost": "8.00000000000004",
"currency": "usd",
"items": [
{
"event_name": "2-X-YOUR-EVENT-NAME-HERE",
"source": "pg-llama3p1-8b_369ff438-YOUR-DEPLOYMENT-ID-HERE",
"total_cost": "8.00000000000004",
"total_usage": "120",
"currency": "usd",
"unit_price": {
"amount": "0.066666666666667",
"currency": "usd"
},
"points": [
{
"timestamp": "2026-05-05T16:00:00Z",
"usage": "8",
"cost": "0.533333333333336",
"event_count": 4
}
]
}
]
}
```
Use `total_cost` (top-level) for the overall total, and each item's `event_name` + `total_cost` for the breakdown by deployment (or by accelerator type with `--group-by accelerator`). For `--plan-type reserved`, `event_name` is already the plain accelerator type (`nvidia-h100`, `nvidia-l40s`, `cpu`).
**Post-processing — pipe JSON to `jq` to read the total, or break it down per item:**
```bash theme={null}
simplismart usage stats \
--plan-type private \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY | jq '.total_cost'
# Per-item breakdown (e.g. per deployment, or per accelerator type with --group-by accelerator)
simplismart usage stats \
--plan-type private \
--start-time 2026-04-01T00:00:00+00:00 \
--end-time 2026-05-01T00:00:00+00:00 \
--window-size DAY | jq '.items[] | {event_name, total_cost}'
```
The `--pg-token` global flag or the `SIMPLISMART_PG_TOKEN` environment variable must be set. All times must be in ISO 8601 format and `start-time` must be before `end-time`.