---
title: "Usage time series (hour or day buckets) from the ledger"
method: GET
path: "/v1/organizations/{organization_id}/usage"
tags: ["Usage and spend"]
---

# Usage time series (hour or day buckets) from the ledger

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

## Request

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

Defaults to the current period at day granularity; hour granularity covers at most 31 days, day at most 400. `workspace_id` / `volume_id` (mutually exclusive) narrow it to one workspace or one shared volume (meter volume_storage_gib_seconds). API keys see only their own project.

## Path parameters

- `organization_id` string, uuid, required

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `granularity` union
  - 'hour'
  - 'day'
- `meter` 'cpu_seconds' | 'memory_gib_seconds' | 'storage_gib_seconds' | 'egress_bytes' | 'ingress_bytes' | 'volume_storage_gib_seconds' | 'gpu_seconds'
- `workspace_id` string, uuid
- `volume_id` string, uuid
- `project_id` string, uuid

## Response `200`

Default Response

- object
  - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `workspace_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `volume_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `project_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `granularity` union, required
    - 'hour'
    - 'day'
  - `from` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `to` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `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.
  - `data` object[], required
    - `start` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `end` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `meter` 'cpu_seconds' | 'memory_gib_seconds' | 'storage_gib_seconds' | 'egress_bytes' | 'ingress_bytes' | 'volume_storage_gib_seconds' | 'gpu_seconds', required
    - `raw_quantity` number, required
    - `billable_quantity` integer, required: Billable units of the bucket outside not-billed windows.
    - `waived_quantity` integer, required: Units measured in hours of the bucket that are not billed (usage summary `waivers`).
    - `finalized` boolean, required: Every hour of the bucket is past the lateness window (later corrections are still possible and are separate ledger rows).
  - `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

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