---
title: "Current-period project usage"
method: GET
path: "/v1/usage/summary"
tags: ["Usage and spend"]
---

# Current-period project usage

`GET /v1/usage/summary`

## Request

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

The project and organization come from the guest delegation or project key. User sessions supply project_id. Meter quantities and measurement are restricted to that project.

## Query parameters

- `project_id` string, uuid

## Response `200`

Default Response

- object
  - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `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.
  - `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

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