---
title: "Spend policy, charges this period, cap state and enforcement (leases, overshoot bound)"
method: GET
path: "/v1/organizations/{organization_id}/spend"
tags: ["Usage and spend"]
---

# Spend policy, charges this period, cap state and enforcement (leases, overshoot bound)

`GET /v1/organizations/{organization_id}/spend`

## Request

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

## 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.
  - `currency` string, nullable, required
  - `overage` string, nullable, required
  - `alert_thresholds` integer[], required
  - `subscription_fee_minor` integer, nullable, required
  - `usage_charges_minor` integer, required: Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor).
  - `estimated_period_total_minor` integer, nullable, required: subscription_fee_minor + usage_charges_minor; null without a subscription price.
  - `cap_state` union, required: Worst state over hard-cap allowances: exhausted (starts refused, see exhausted_reason) > overage (past an allowance, charged under the spend cap) > warning (80 % or more) > ok.
    - 'ok'
    - 'warning'
    - 'overage'
    - 'exhausted'
  - `exhausted` string[], required
  - `exhausted_reason` union, required
    - 'allowance_used'
    - 'overage_paused'
    - 'spend_cap_reached'
  - `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.
  - `enforcement` object, required
    - `new_starts` union, required: refused while any hard-cap allowance is exhausted (402 allowance_exhausted with exhausted_reason as details.reason).
      - 'allowed'
      - 'refused'
    - `running_workspaces` integer, required
    - `suspension` string, required: How running workspaces are stopped when a hard cap is reached.
    - `leases` object[], required
      - `id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `cell_id` string, required
      - `sequence` integer, required
      - `state` string, required
      - `capped` boolean, required
      - `cpu_seconds` number, required
      - `memory_gib_seconds` number, required
      - `transfer_bytes` integer, nullable, required
      - `usage_from` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `issued_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `expires_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `end_reason` string, nullable, required
      - `burn_rate` object, required
        - `cpu_seconds_per_second` number, required
        - `memory_gib` number, required
        - `workspaces` integer, required
      - `overshoot_bound` object, required
        - `cpu_seconds` number, required
        - `memory_gib_seconds` number, required
      - `cell_consumed_cpu_seconds` number, nullable, required
      - `cell_consumed_memory_gib_seconds` number, nullable, required
      - `cell_acknowledged_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `overshoot_bound` object, required
      - `cpu_seconds` number, required
      - `memory_gib_seconds` number, required
      - `note` string, required
  - `meter_submissions` object, nullable, required: Stripe meter submission states (owner/billing only; null otherwise).
  - `cell_enforcement` object, nullable, required: What the cell enforces from the leases (cell.org_spend_state): exhausted = hosts paused billable execution and the cell refuses queued starts. Null until the cell has evaluated a lease of this organization.
    - `state` union, required
      - 'ok'
      - 'exhausted'
    - `meter` string, nullable, required
    - `reason` string, nullable, required
    - `since` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `details` object, required

## 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)