---
title: "Current-period usage, included allowances and cap state of an organization"
method: GET
path: "/v1/organizations/{organization_id}/usage/summary"
tags: ["Usage and spend"]
---

# Current-period usage, included allowances and cap state of an organization

`GET /v1/organizations/{organization_id}/usage/summary`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/organizations/{organization_id}/usage/summary`
- Auth: HTTP bearer

Totals come from the usage ledger (hourly, finalized after the lateness window); `measurement.measured_through` says how far usage is complete. Billable units are whole units (floor per workspace-hour); allowance usage counts billable units. `allowance_exhausted` true means new opens/resumes answer 402 `allowance_exhausted` with `exhausted_reason` as details.reason. `spend_cap` is opt-in overage this period: while it is on, a CPU-hours or RAM GiB-hours allowance past `included` is in cap state `overage` (starts admitted, usage past it charged) until the spend cap is reached.

## Path parameters

- `organization_id` string, uuid, required

## Response `200`

Default Response

- object
  - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `plan` object, nullable, required
    - `plan_key` string, required
    - `catalog_version` string, required
    - `priority` string, nullable, required
    - `overage` string, nullable, required
  - `period` object, required
    - `start` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `end` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `resets_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `source` union, required: The entitling subscription period; `custom_plan`: a month of a custom plan, counted from its start (the last one ends with the plan); `grant`: the window of a time-limited plan grant (a trial or partner grant), which ends at `end` rather than resetting; else the calendar month (UTC), counted from the end of a trial or partner grant or a custom plan that ended in it.
      - 'subscription'
      - 'calendar_month'
      - 'grant'
      - 'custom_plan'
    - `counted_from` string, date-time, required: First hour whose usage counts in this period (RFC 3339 UTC). Usage is metered per UTC hour, and each hour belongs to the period that contains its start (the hour's ledger rows keep the plan in force at that instant and are sent to Stripe with that timestamp). When the period starts inside an hour (after a plan change, or a subscription created mid-hour), that hour's usage counts toward the previous period, so counted_from is `start` rounded up to the next full hour; on a full hour it equals `start`. Before counted_from passes, the period has no counted usage (`estimate_status` no_data) even while workspaces run: their usage is in the usage series under the hour containing `start`.
  - `measurement` object, required: Measurement freshness: estimates are complete up to measured_through.
    - `measured_through` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `finalized_through` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `estimate_status` union, required: provisional: includes hours not yet finalized (lateness window); incomplete: measurement gaps in the period (never zero-filled); final: every hour of the range is finalized.
      - 'no_data'
      - 'provisional'
      - 'final'
      - 'incomplete'
    - `running_workspaces` integer, required
    - `unmeasured_running_workspaces` integer, required: Running workspaces without any usage record yet.
    - `live_volumes` integer, required: Shared volumes in state available (storage accrues); their last measurement bounds measured_through.
    - `unmeasured_live_volumes` integer, required: Live shared volumes without any storage measurement yet.
    - `measurement_gaps` object, required: Unmeasured intervals (workspace usage records and shared-volume storage measurements): never zero-filled, never billed.
      - `count` integer, required
      - `seconds` number, required
      - `last_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `source_status` string, required: Usage source (cell ingestion) status: available | unavailable | incompatible | unknown.
    - `last_rollup_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `allowance_exhausted` boolean, required
  - `exhausted` object[], required
    - `allowance` string, required
    - `meter` 'cpu_seconds' | 'memory_gib_seconds' | 'storage_gib_seconds' | 'egress_bytes' | 'ingress_bytes' | 'volume_storage_gib_seconds' | 'gpu_seconds', required
    - `used` number, required
    - `included` number, nullable, required
    - `unit` string, required
  - `exhausted_reason` union, required
    - 'allowance_used'
    - 'overage_paused'
    - 'spend_cap_reached'
  - `egress_override` object, nullable, required: Active organization egress override: outbound internet traffic of every workspace is blocked until an upgrade/purchase raises the allowance or the period ends (lifts_at).
    - `mode` 'deny_all', required
    - `reason` 'transfer_allowance_exhausted', required
    - `allowance` string, required
    - `set_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `lifts_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `gpu` object, nullable, required: GPU-hours this period. One GPU-hour accrues per hour at the larger of the scene GPU memory over 16 GiB and the GPU busy fraction. Null when the plan includes no GPU-hours and nothing was used.
    - `included_hours` number, nullable, required: GPU-hours included this period.
    - `used_hours` number, required: GPU-hours used this period (billable units).
    - `overage_hours` number, required: GPU-hours used past the included amount this period (charged or not).
    - `billed_overage_hours` number, required: The part of overage_hours charged under the spend cap (spend_cap line gpu_hours).
    - `cap_state` union, required
      - 'ok'
      - 'warning'
      - 'overage'
      - 'gpu_blocked'
      - 'not_included'
    - `blocked_reason` union, required
      - 'allowance_used'
      - 'overage_paused'
      - 'spend_cap_reached'
  - `allowances` object[], required
    - `key` string, required
    - `display_name` string, required
    - `unit` string, required
    - `meters` string[], required
    - `enforcement` union, required: hard_cap: exhausting it refuses opens/resumes (402 allowance_exhausted) and running workspaces are suspended; spare_capacity: no allowance cap (runs on reclaimable spare capacity); reported: shown and notified, never enforced by refusing access; egress_block (outbound_transfer_gb): at 100% outbound internet traffic is blocked by an organization egress override until upgrade, purchase or the next period (workspaces keep running, starts are not refused); storage_block (retained_state_gib): at 100% opening a new workspace key and forking are refused (403 quota_exceeded, details.limit retained_state) until retained state is below the allowance (existing workspaces keep running, waking, suspending and resuming; nothing is deleted or charged); gpu_block (gpu_hours): at 100%, unless opt-in overage covers GPU-hours, GPU rendering stops until the next period, an upgrade or overage (workspaces keep running, starts are not refused).
      - 'hard_cap'
      - 'spare_capacity'
      - 'reported'
      - 'egress_block'
      - 'storage_block'
      - 'gpu_block'
    - `included` number, nullable, required
    - `used` number, required
    - `remaining` number, nullable, required
    - `percent_used` number, nullable, required
    - `included_meter_units` number, nullable, required
    - `used_meter_units` number, nullable, required
    - `remaining_meter_units` number, nullable, required
    - `cap_state` union, required: ok: below 80 %. warning: 80 % or more of the allowance. exhausted: a hard cap is used up and starts are refused (402 allowance_exhausted; see exhausted_reason). overage: a CPU-hours or RAM GiB-hours allowance is used up while opt-in overage is on and below its spend cap, so starts are admitted and the usage past it is charged (spend_cap). over_allowance: a reported allowance is exceeded (never refused). egress_blocked: the outbound transfer allowance is used up and outbound traffic is blocked. storage_blocked: the retained state allowance is used up and new workspaces and forks are refused (403 quota_exceeded). gpu_blocked: the GPU-hours allowance is used up and GPU rendering is stopped (see gpu.blocked_reason); workspaces keep running. uncapped: runs on spare capacity. not_included: the plan does not define it.
      - 'ok'
      - 'warning'
      - 'exhausted'
      - 'overage'
      - 'over_allowance'
      - 'egress_blocked'
      - 'storage_blocked'
      - 'gpu_blocked'
      - 'uncapped'
      - 'not_included'
  - `meters` object[], required
    - `meter` 'cpu_seconds' | 'memory_gib_seconds' | 'storage_gib_seconds' | 'egress_bytes' | 'ingress_bytes' | 'volume_storage_gib_seconds' | 'gpu_seconds', required
    - `unit` string, required
    - `display_name` string, required
    - `raw_quantity` number, required: Measured quantity in meter units (fractional), not-billed hours included.
    - `billable_quantity` integer, required: Whole units billed: floor of the raw quantity per workspace-hour, outside not-billed windows (`waivers`).
    - `waived_quantity` integer, required: Whole units measured in hours that are not billed (`waivers`); 0 without any.
    - `stripe_event_name` string, nullable, required
  - `alert_thresholds` integer[], required
  - `spend_cap` SpendCap, required: Opt-in overage with a spend cap. Off by default. While it is on, workspaces open and run past the plan’s CPU-hours and RAM GiB-hours allowances, and the usage past them is charged at the rates below, up to the effective cap per billing period. At the cap, and while a plan invoice is past due, a used-up allowance refuses new starts (402 allowance_exhausted) and running workspaces are paused. Nothing is deleted.
    - `state` union, required: unavailable: the plan has no opt-in overage or the organization has no paid subscription. off: available, not turned on. paused: on, but a plan invoice is past due, so overage behaves as off until it is paid. within_allowance: on, no usage past the allowances yet. accruing: on, usage past an allowance is being charged. warning: charges are 80 % of the effective cap or more. reached: less than one cent of the cap is left, so starts are refused (402 allowance_exhausted, reason spend_cap_reached) and running workspaces are paused.
      - 'unavailable'
      - 'off'
      - 'paused'
      - 'within_allowance'
      - 'accruing'
      - 'warning'
      - 'reached'
    - `available` boolean, required: The plan offers opt-in overage (catalog overage `opt_in`) and the organization pays for the plan with a subscription.
    - `enabled` boolean, required: An owner or billing member turned overage on (spend-policy overage_enabled).
    - `paused` boolean, required: A plan invoice is past due (payment grace or restriction): overage behaves as off until it is paid.
    - `cap_minor` integer, nullable, required: The configured spend cap per billing period, minor units of `currency`. Null: never set.
    - `effective_cap_minor` integer, required: The cap that applies: min(cap_minor, max_cap_minor), or max_cap_minor when no cap is set. 0 when overage is unavailable.
    - `max_cap_minor` integer, nullable, required: The current plan price: the largest cap that can be set, so a downgrade lowers the effective cap. Null without a subscription price.
    - `charges_minor` integer, required: Overage charged this period so far, whole minor units (floor). It is billed on the next invoice and never exceeds the effective cap. Accrued charges stay when overage is turned off or paused.
    - `remaining_minor` integer, required: What is left under the effective cap, whole minor units (floor).
    - `percent_of_cap` number, nullable, required: Charges as a percentage of the effective cap (2 decimals). Null when overage is unavailable.
    - `currency` string, required: ISO 4217 code, lower case (the plan price currency).
    - `resets_at` string, date-time, required: When the billing period ends: charges and the cap start again from zero.
    - `lines` object[], required: One line per dimension, RAM first (the invoice lines of the period). Empty when the plan has no overage rates.
      - `allowance` union, required: The allowances overage covers (gpu_hours on plans with a GPU-hour rate). Storage and transfer never accrue overage.
        - 'ram_gib_hours'
        - 'cpu_hours'
        - 'gpu_hours'
      - `unit` union, required: gib_hours for ram_gib_hours, hours for cpu_hours (CPU-hours) and gpu_hours (GPU-hours).
        - 'gib_hours'
        - 'hours'
      - `units_over` number, required: Usage past the allowance this period, in unit-hours (charged or not: usage before overage was turned on, while paused or past the cap is never charged).
      - `billed_units` number, required: The part of it charged this period, in unit-hours.
      - `rate_minor` number, required: Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour; 12 = $0.12 per CPU-hour).
      - `amount_minor` integer, required: billed_units × rate_minor, whole minor units (floor). Lines are floored one by one, so they may add up to one minor unit less than charges_minor.
    - `projected_reached_at` string, date-time, nullable, required: When the charges reach the effective cap at the average burn of this period so far. Null when not accruing or when it would fall after resets_at.
  - `template_storage` OrgTemplateStorage, required: Template storage of the organization; it counts toward the retained_state_gib allowance.
    - `bytes` integer, required: The organization’s template storage: distinct org layer bytes plus full-image deltas; platform bases never count.
    - `plan_storage_bytes` integer, nullable, required
    - `share` number, nullable, required
    - `warnings` TemplateStorageWarning[], required
    - `largest` object[], required: The 5 largest templates.
      - `template_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `slug` string, required
      - `bytes` integer, required
      - `share` number, nullable, required
  - `waivers` object[], required: Not-billed windows of this period and later.
    - `starts_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `ends_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `active` boolean, required: The window is in progress now.
  - `custom_plan` object, nullable, required: The custom plan in force, arranged with Shardflux and invoiced directly (price and terms: GET .../billing/subscription custom_plan); null otherwise.
    - `name` string, required: Display name, e.g. "Scale (custom)".
    - `base_plan_key` string, required
    - `billing` 'manual_invoice', required
    - `starts_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `ends_at` string, date-time, required: RFC 3339 UTC timestamp with Z.

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)