---
title: "Read customer pool utilization from retained device hours"
method: GET
path: "/v1/pools/{id}/utilization"
tags: ["Pools"]
---

# Read customer pool utilization from retained device hours

`GET /v1/pools/{id}/utilization`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/pools/{id}/utilization`
- Auth: HTTP bearer

Read-only and available to account members. Defaults to the last 168 complete hours, ending at the current UTC hour. From is inclusive and to is exclusive. Both must align to UTC hours and the window must be positive and at most 31 days. Future or incomplete hours are rejected. Day buckets follow UTC calendar boundaries and may have shorter first or last buckets. The response includes current hosts without evidence and removed hosts with retained history. Queries never read raw telemetry. Requests over 100000 device-hour rows or host buckets return 422 instead of partial totals. Narrow the time window to retry.

## Path parameters

- `id` string, required

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `bucket` 'hour' | 'day'

## Response `200`

Retained utilization and explicit measurement availability.

- PoolUtilization
  - `pool_id` string, required
  - `from` string, date-time, required
  - `to` string, date-time, required
  - `bucket` 'hour' | 'day', required
  - `summary` PoolUtilizationMetrics, required: Totals cover retained ready-device hourly rows only. Complete means all represented ready seconds have activity evidence, not that the pool existed throughout the requested range. Partial means some ready seconds lack observations and all activity totals and percentages are null. No data means no retained rows. Zero capacity has null percentages. Missing activity is never counted as idle or stranded. Fragmentation, queued and burst are unavailable without Route and remain null in the observe ledger. Route measurements use independent durable queue and execution evidence in the pool summary. Host summaries and host buckets keep Route fields null because these cannot be attributed to a private host.
    - `capacity_seconds` integer, required
    - `unknown_seconds` integer, required
    - `allocated_seconds` integer, nullable, required
    - `busy_seconds` integer, nullable, required
    - `idle_allocated_seconds` integer, nullable, required
    - `stranded_seconds` integer, nullable, required
    - `foreign_seconds` integer, nullable, required
    - `fragmentation_seconds` integer, nullable, required: Workload-seconds when a multi-device request waited because free devices were split across hosts.
    - `queued_seconds` integer, nullable, required: Workload-seconds waiting for the pool. Null when retained queue history cannot cover the window.
    - `burst_seconds` integer, nullable, required: Settled customer-active burst device-seconds clipped to the requested window.
    - `allocation_pct` number, nullable, required
    - `busy_pct` number, nullable, required
    - `busy_of_allocated_pct` number, nullable, required
    - `data_status` 'complete' | 'partial' | 'no_data', required
    - `burst_cost_micros` integer, nullable, required: Exact settled customer cost in USD micros for burst executions wholly inside the requested window. Null when unsettled or crossing the window boundary.
  - `hosts` PoolUtilizationHost[], required
    - `host_id` string, required
    - `name` string, required
    - `device_count` integer, required
    - `summary` PoolUtilizationMetrics, required: Totals cover retained ready-device hourly rows only. Complete means all represented ready seconds have activity evidence, not that the pool existed throughout the requested range. Partial means some ready seconds lack observations and all activity totals and percentages are null. No data means no retained rows. Zero capacity has null percentages. Missing activity is never counted as idle or stranded. Fragmentation, queued and burst are unavailable without Route and remain null in the observe ledger. Route measurements use independent durable queue and execution evidence in the pool summary. Host summaries and host buckets keep Route fields null because these cannot be attributed to a private host.
      - `capacity_seconds` integer, required
      - `unknown_seconds` integer, required
      - `allocated_seconds` integer, nullable, required
      - `busy_seconds` integer, nullable, required
      - `idle_allocated_seconds` integer, nullable, required
      - `stranded_seconds` integer, nullable, required
      - `foreign_seconds` integer, nullable, required
      - `fragmentation_seconds` integer, nullable, required: Workload-seconds when a multi-device request waited because free devices were split across hosts.
      - `queued_seconds` integer, nullable, required: Workload-seconds waiting for the pool. Null when retained queue history cannot cover the window.
      - `burst_seconds` integer, nullable, required: Settled customer-active burst device-seconds clipped to the requested window.
      - `allocation_pct` number, nullable, required
      - `busy_pct` number, nullable, required
      - `busy_of_allocated_pct` number, nullable, required
      - `data_status` 'complete' | 'partial' | 'no_data', required
      - `burst_cost_micros` integer, nullable, required: Exact settled customer cost in USD micros for burst executions wholly inside the requested window. Null when unsettled or crossing the window boundary.
    - `buckets` PoolUtilizationBucket[], required
      - `start` string, date-time, required
      - `end` string, date-time, required
      - `metrics` PoolUtilizationMetrics, required: Totals cover retained ready-device hourly rows only. Complete means all represented ready seconds have activity evidence, not that the pool existed throughout the requested range. Partial means some ready seconds lack observations and all activity totals and percentages are null. No data means no retained rows. Zero capacity has null percentages. Missing activity is never counted as idle or stranded. Fragmentation, queued and burst are unavailable without Route and remain null in the observe ledger. Route measurements use independent durable queue and execution evidence in the pool summary. Host summaries and host buckets keep Route fields null because these cannot be attributed to a private host.
        - `capacity_seconds` integer, required
        - `unknown_seconds` integer, required
        - `allocated_seconds` integer, nullable, required
        - `busy_seconds` integer, nullable, required
        - `idle_allocated_seconds` integer, nullable, required
        - `stranded_seconds` integer, nullable, required
        - `foreign_seconds` integer, nullable, required
        - `fragmentation_seconds` integer, nullable, required: Workload-seconds when a multi-device request waited because free devices were split across hosts.
        - `queued_seconds` integer, nullable, required: Workload-seconds waiting for the pool. Null when retained queue history cannot cover the window.
        - `burst_seconds` integer, nullable, required: Settled customer-active burst device-seconds clipped to the requested window.
        - `allocation_pct` number, nullable, required
        - `busy_pct` number, nullable, required
        - `busy_of_allocated_pct` number, nullable, required
        - `data_status` 'complete' | 'partial' | 'no_data', required
        - `burst_cost_micros` integer, nullable, required: Exact settled customer cost in USD micros for burst executions wholly inside the requested window. Null when unsettled or crossing the window boundary.
      - `foreign_device_ids` string[], required

## Other responses

- `400`: Malformed, duplicate or unsupported query fields or invalid time range.
- `422`: Result exceeds the full-response bound. Narrow the time window.
- `default`: Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)