Analytics Commands

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.

simplismart usage stats [options]

Option	Description
`--plan-type TYPE`	Compute plan to query (required). See 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`, `reserved`
`--deployment-slug a,b,...`	Filter by deployment slug(s). Same scope as `--deployment-id` above
`--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`
`--statuses a,b,...`	Restrict to exactly these resource statuses (e.g. `DEPLOYED`, `STOPPED`, `DELETED`, `FAILED` for deployments; `SUCCESS`, `FAILED` for compilation). Omit for no restriction — every status is included by default. No effect 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`, `accelerator` (or omitting `--group-by`, with no deployment filter) also gets you the reservation commitment breakdown automatically — see the Reserved example below

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.

You can find workspace-id under Settings > Workspaces. Select your workspace and copy the workspace ID.

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

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

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 <WORKSPACE_ID>

Dedicated/BYOC usage (private): daily cost scoped to deployments by --deployment-id (comma-separated UUIDs)

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 <UUID_1>,<UUID_2>

Shared usage (shared): daily cost filtered to inference on specific --model-name values

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)

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:

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 --group-by accelerator (or omitting --group-by, with no deployment filter) gets you the full commitment breakdown automatically — no flag to pass:

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}]}'

# reservation_commitment is a separate, top-level field alongside items/total_cost -
# one entry per accelerator type your org has committed to, each with a `daily`
# array of per-window overage/true-up figures:
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 '.reservation_commitment'

total_cost reflects what your org is actually billed under the reservation. computed_overage_amount is usage billed above what you’ve committed to for that window; computed_true_up_amount is committed capacity you paid for but didn’t use that window. If your org moved from a private plan to a reserved plan, items includes usage from before that migration too, so you get one continuous view instead of a gap at the migration date.

--group-by deployment never returns the commitment breakdown — overage/true-up cost is pooled across your whole account and can’t be attributed to a single deployment, so a pooled, account-wide figure sitting next to a per-deployment cost list would be misleading. Use --group-by accelerator (or omit --group-by) whenever you want the breakdown.--deployment-id/--deployment-slug can’t be combined with an explicit --group-by accelerator — the SDK rejects it locally, and the backend rejects it too (400), since a pooled/accelerator-grouped query never resolves per-deployment sources at all. Omitting --group-by alongside a deployment filter is fine — for --plan-type reserved it auto-corrects to --group-by deployment instead of defaulting to the pooled shape.

--group-by deployment gets you a flat per-deployment metered cost list instead — it never includes the commitment breakdown:

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 '.items[] | {source, event_name, total_cost}'

--group-by can be omitted for a deployment-filtered reserved query too — --deployment-id/--deployment-slug auto-correct an omitted --group-by to the per-deployment shape:

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 \
  --deployment-id <UUID_1>,<UUID_2>

Private/Reserved: pooled per-accelerator-type breakdown instead of per-deployment

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, the breakdown always covers your whole account, and only appears with --group-by accelerator (or --group-by omitted). 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:

{
  "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`	Never carries these fields - use `accelerator` for that data instead

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:

{
  "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:

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.

Python SDK Reference

CLI Reference

Cost & Usage

Usage Stats

Plan Types

​Cost & Usage

​Usage Stats

​Plan Types

Cost & Usage

Usage Stats

Plan Types