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`
`--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.

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

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:

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

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:

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

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