---
title: Usage | Runware Docs
url: https://runware.ai/docs/serverless/api-usage
description: Read the usage ledger, summarize GPU time and spend over a window, and report reserved capacity against it.
relatedDocuments:
  - https://runware.ai/docs/serverless/api
  - https://runware.ai/docs/serverless/pricing
  - https://runware.ai/docs/serverless/api-monitoring
---
## Introduction

Usage is recorded as **an append-only ledger, one row per worker state transition**, each carrying the GPU count and the rate that applied. Everything else here is derived from it on read. [Pricing](https://runware.ai/docs/serverless/pricing) explains what is billed and why.

Totals are never stored, so **a window that cannot be priced in full fails rather than reporting a smaller number**. A total that silently omits usage is a wrong number the caller cannot see is wrong.

## List usage events

GETapi.serverless.runware.ai/v1/usage

Append-only billing telemetry. One row per worker state transition. `appId` narrows the page to one app, the copy `environment` selects (`production` by default); without `appId` the page spans the organization and `environment` narrows nothing.

> [!NOTE]
> Events are drawn on when the transition happened, not when it was recorded, so ingest lag never moves one across a boundary. `busy` never appears: it describes queue occupancy rather than a change in the worker's life, and a worker costs the same whether it is serving or waiting.

### [Request](#list-usage-events-request)

Query

### [limit](#list-usage-events-query-limit)

- **Type**: `integer`
- **Format**: `int32`
- **Min**: `1`
- **Max**: `100`
- **Default**: `20`

Maximum number of items to return.

### [cursor](#list-usage-events-query-cursor)

- **Type**: `string`

Opaque pagination cursor returned by a previous call, as `nextCursor` or, on the operations that offer one, `prevCursor`.

### [appId](#list-usage-events-query-appid)

- **Type**: `string`
- **Min**: `6`
- **Max**: `30`

Immutable app identifier. Unique among the authenticated organization's live apps in one environment: it cannot be changed after creation, it becomes available again once the app it named reaches `deleted`, and the same id may run once in each environment as a separate copy.

### [environment](#list-usage-events-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [from](#list-usage-events-query-from)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Inclusive lower bound on event time (RFC 3339).

### [to](#list-usage-events-query-to)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Exclusive upper bound on event time (RFC 3339).

### [Response](#list-usage-events-response)

### [nextCursor](#list-usage-events-response-nextcursor)

- **Type**: `string (nullable)`

Cursor for the next page. Null when there are no more items.

### [data](#list-usage-events-response-data)

- **Type**: `object[] (12 properties)`

#### [id](#list-usage-events-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [appId](#list-usage-events-response-data-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier. Unique among the authenticated organization's live apps in one environment: it cannot be changed after creation, it becomes available again once the app it named reaches `deleted`, and the same id may run once in each environment as a separate copy.

#### [environment](#list-usage-events-response-data-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the app's copy runs in.

#### [workerId](#list-usage-events-response-data-workerid)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [eventType](#list-usage-events-response-data-eventtype)

- **Type**: `string`
- **Required**: true

Status the worker transitioned into. The ledger emits a subset of `WorkerStatus`. `busy` never appears (queue occupancy, not a pod lifecycle transition). Consecutive rows of one worker can carry the same status.

**Possible values**: `pending` `pulling` `loading` `ready` `busy` `unhealthy` `draining` `stopping` `stopped`

#### [gpuCount](#list-usage-events-response-data-gpucount)

- **Type**: `integer`
- **Required**: true
- **Format**: `int32`

#### [gpuType](#list-usage-events-response-data-gputype)

- **Type**: `string`
- **Min**: `1`
- **Max**: `64`

GPU type the worker held at the transition. Absent when the worker held no GPU.

#### [pricePerSecond](#list-usage-events-response-data-pricepersecond)

- **Type**: `object (2 properties)`

Catalog price per GPU per second in force at `occurredAt`, resolved from the catalog history. Absent when `gpuType` is absent or the catalog history has no applicable price. This is the positive pay-as-you-go rate whatever covered the time. Reserved capacity is not a discount on it: coverage is reported by `GET /v1/usage/summary` and never by a rate of zero.

##### [amount](#list-usage-events-response-data-pricepersecond-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#list-usage-events-response-data-pricepersecond-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

#### [occurredAt](#list-usage-events-response-data-occurredat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

When the transition happened. This is the event time the `from` and `to` filters apply to, and the field to bill on.

#### [createdAt](#list-usage-events-response-data-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

When the event was recorded. Audit only. May lag `occurredAt`.

### [Errors](#list-usage-events-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Summarize usage

GETapi.serverless.runware.ai/v1/usage/summary

GPU time and spend for the authenticated organization, or for one of its environments, aggregated over a half-open window and grouped by the dimensions asked for. `environment` narrows what is reported, not what is measured: a capacity commitment covers the organization's concurrent GPUs in every environment, so one environment's figures are its share of that coverage. Every figure is derived on read from the immutable usage ledger, the effective-dated price catalog and the organization's capacity commitments. Two consequences follow. The window is bounded, because the read folds every event of every worker in it. And a worker whose recorded life cannot be priced fails the request rather than being left out of the totals, because a total that silently omits usage is a wrong number a caller cannot see is wrong. These failures return `500`, with no partial totals. `paygSpend` is provisional pay-as-you-go accrual, not a settled charge. It excludes whole-second finalization rounding and ledger adjustments. `paygEquivalentValue` prices the same time at the catalog rate whatever covered it, so the difference between them is what a capacity commitment, or the platform, paid for. Time covered by a capacity commitment or by the platform settles at zero, so only pay-as-you-go is drawn from credit.

> [!NOTE]
> `paygSpend` is provisional accrual, not a settled charge: it excludes whole-second finalization rounding and ledger adjustments. `paygEquivalentValue` prices the same time at the catalog rate whatever covered it, so the gap between the two is what a [reserved capacity](https://runware.ai/docs/serverless/pricing#reserved-capacity) commitment, or the platform itself, paid for. Both settle at zero, so only pay-as-you-go time is drawn from credit.
> 
> `timezone` takes an IANA name and decides where a calendar day and a clock hour begin, UTC when omitted. `from` and `to` stay exact instants either way, so the window is the same and only the buckets move.

### [Request](#get-usage-summary-request)

Query

### [from](#get-usage-summary-query-from)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Inclusive lower bound on billable time (RFC 3339). Defaults to 24 hours before `to`. The maximum elapsed window is 48 hours when `groupBy` includes `hour`, otherwise 31 days. Timezone selection does not change this instant. An explicit zero timestamp (`0001-01-01T00:00:00Z`) returns `422` rather than selecting the default.

### [to](#get-usage-summary-query-to)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Exclusive upper bound on billable time (RFC 3339). Defaults to now, and a value in the future is read as now. An explicit zero timestamp (`0001-01-01T00:00:00Z`) returns `422` rather than selecting the default.

### [appId](#get-usage-summary-query-appid)

- **Type**: `string`
- **Min**: `6`
- **Max**: `30`

Report only this app's usage, the copy `environment` selects. A filter on what is reported, not on what is measured: coverage depends on every app's concurrent GPUs.

### [environment](#get-usage-summary-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

Report only this environment's usage. Omitted, the report covers every environment of the organization, except that `appId` alone names the app's `production` copy. A name the organization has no live environment under returns `404`.

### [gpuType](#get-usage-summary-query-gputype)

- **Type**: `string`
- **Min**: `1`
- **Max**: `64`

Report only usage of this GPU type. A retired type is accepted, because usage recorded before it was withdrawn is still reportable. A type the catalog has never carried returns `422`.

### [groupBy](#get-usage-summary-query-groupby)

- **Type**: `string[]`

Dimensions to group by. An empty list returns one bucket for the whole window when there is billable time. Usage with no billable milliseconds produces no bucket, for any grouping. Each dimension appears on the bucket it was requested with and is absent otherwise. Grouped by `app`, each environment's copy of an app is its own bucket. Grouped by `hour`, the resolved window must not exceed 48 elapsed hours, including when other dimensions are requested. The limit applies after defaults and future-end clamping.

### [timezone](#get-usage-summary-query-timezone)

- **Type**: `string`
- **Max**: `255`
- **Default**: `UTC`

IANA timezone name for calendar-day and clock-hour grouping, for example `Europe/London`. Defaults to UTC when omitted. Empty, invalid and server-local (`Local`) names return `422`. The RFC 3339 `from` and `to` values remain exact instants, not local clock values. Day buckets follow local calendar dates. Repeated hours are separate occurrences; nonexistent hours produce no bucket. Offset transitions can create partial hours. Missing midnight starts its date at the first existing instant, and repeated midnight belongs to one date bucket. Empty buckets are not filled.

### [Response](#get-usage-summary-response)

### [from](#get-usage-summary-response-from)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

Inclusive start of the reported window, as resolved.

### [to](#get-usage-summary-response-to)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

Exclusive end of the reported window, as resolved.

### [buckets](#get-usage-summary-response-buckets)

- **Type**: `object[] (13 properties)`
- **Required**: true

#### [appId](#get-usage-summary-response-buckets-appid)

- **Type**: `string`
- **Min**: `6`
- **Max**: `30`

Present when grouped by `app`.

#### [environment](#get-usage-summary-response-buckets-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

Present when grouped by `app`; the environment the app's copy runs in.

#### [gpuType](#get-usage-summary-response-buckets-gputype)

- **Type**: `string`
- **Min**: `1`
- **Max**: `64`

Present when grouped by `gpuType`.

#### [day](#get-usage-summary-response-buckets-day)

- **Type**: `string`
- **Format**: `date`

Calendar date in the requested timezone, UTC by default. Present when grouped by `day`. A span crossing local midnight is divided between the dates it ran on.

#### [hour](#get-usage-summary-response-buckets-hour)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Actual start of the local clock-hour occurrence, serialized in UTC. Present when grouped by `hour`. It can precede `from` for a partial first bucket. Repeated hours have distinct starts, and an offset transition can start a partial hour.

#### [coverage](#get-usage-summary-response-buckets-coverage)

- **Type**: `string`

Present when grouped by `coverage`.

**Possible values**: `commitment` `payg` `platform`

#### [gpuMilliseconds](#get-usage-summary-response-buckets-gpumilliseconds)

- **Type**: `integer`
- **Required**: true
- **Format**: `int64`
- **Min**: `0`

Billable GPU time, summed over each GPU separately. A worker holding four GPUs for one second contributes four thousand. Under billing policy `serverless-billing-v3` every span is counted in whole milliseconds rounded up, so a span shorter than a millisecond counts as one; usage recorded under an earlier policy keeps the count it was recorded under. A span crossing calendar boundaries is divided so its buckets sum to the span's own count.

#### [paygSpend](#get-usage-summary-response-buckets-paygspend)

- **Type**: `object (2 properties)`
- **Required**: true

Provisional pay-as-you-go accrual for this time, excluding finalization rounding and ledger adjustments. Zero for time a commitment or the platform covered.

##### [amount](#get-usage-summary-response-buckets-paygspend-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#get-usage-summary-response-buckets-paygspend-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

#### [paygEquivalentValue](#get-usage-summary-response-buckets-paygequivalentvalue)

- **Type**: `object (2 properties)`
- **Required**: true

The same time priced at the catalog rate, whatever covered it. The difference from `paygSpend` is what reserved capacity saved and what the platform paid for.

##### [amount](#get-usage-summary-response-buckets-paygequivalentvalue-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#get-usage-summary-response-buckets-paygequivalentvalue-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

### [total](#get-usage-summary-response-total)

- **Type**: `object (13 properties)`
- **Required**: true

The whole window with no grouping. It carries no dimension fields, and it always equals the sum of `buckets`.

#### [appId](#get-usage-summary-response-total-appid)

- **Type**: `string`
- **Min**: `6`
- **Max**: `30`

Present when grouped by `app`.

#### [environment](#get-usage-summary-response-total-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

Present when grouped by `app`; the environment the app's copy runs in.

#### [gpuType](#get-usage-summary-response-total-gputype)

- **Type**: `string`
- **Min**: `1`
- **Max**: `64`

Present when grouped by `gpuType`.

#### [day](#get-usage-summary-response-total-day)

- **Type**: `string`
- **Format**: `date`

Calendar date in the requested timezone, UTC by default. Present when grouped by `day`. A span crossing local midnight is divided between the dates it ran on.

#### [hour](#get-usage-summary-response-total-hour)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Actual start of the local clock-hour occurrence, serialized in UTC. Present when grouped by `hour`. It can precede `from` for a partial first bucket. Repeated hours have distinct starts, and an offset transition can start a partial hour.

#### [coverage](#get-usage-summary-response-total-coverage)

- **Type**: `string`

Present when grouped by `coverage`.

**Possible values**: `commitment` `payg` `platform`

#### [gpuMilliseconds](#get-usage-summary-response-total-gpumilliseconds)

- **Type**: `integer`
- **Required**: true
- **Format**: `int64`
- **Min**: `0`

Billable GPU time, summed over each GPU separately. A worker holding four GPUs for one second contributes four thousand. Under billing policy `serverless-billing-v3` every span is counted in whole milliseconds rounded up, so a span shorter than a millisecond counts as one; usage recorded under an earlier policy keeps the count it was recorded under. A span crossing calendar boundaries is divided so its buckets sum to the span's own count.

#### [paygSpend](#get-usage-summary-response-total-paygspend)

- **Type**: `object (2 properties)`
- **Required**: true

Provisional pay-as-you-go accrual for this time, excluding finalization rounding and ledger adjustments. Zero for time a commitment or the platform covered.

##### [amount](#get-usage-summary-response-total-paygspend-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#get-usage-summary-response-total-paygspend-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

#### [paygEquivalentValue](#get-usage-summary-response-total-paygequivalentvalue)

- **Type**: `object (2 properties)`
- **Required**: true

The same time priced at the catalog rate, whatever covered it. The difference from `paygSpend` is what reserved capacity saved and what the platform paid for.

##### [amount](#get-usage-summary-response-total-paygequivalentvalue-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#get-usage-summary-response-total-paygequivalentvalue-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

### [calculatedAt](#get-usage-summary-response-calculatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

The instant the figures describe.

### [Errors](#get-usage-summary-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Credit balance

GETapi.serverless.runware.ai/v1/credit-pool

The authenticated organization's Serverless credit pool, read as one snapshot at `observedAt`. Serverless credit is separate from inference credit. `availableBalance` is `totalBalance` minus `heldCredit`, and can be negative. Held credit is set aside for capacity that is running or starting. It has not been spent and is unrelated to reserved capacity. An arrears account is invoiced for its usage and holds no prepaid balance, so both balances are `null` rather than zero. Until Serverless billing is active for the organization, this returns `404`, which is not a zero balance. The balance and the `404` are sent with `Cache-Control: no-store`.

> [!NOTE]
> A `404` here means Serverless billing is not active for the organization yet. **It is not a zero balance**, and the two are worth telling apart before showing a customer a number.

### [Response](#get-credit-pool-response)

### [collectionMode](#get-credit-pool-response-collectionmode)

- **Type**: `string`
- **Required**: true

How the organization pays for Serverless usage. `prepaid` usage draws down credit bought in advance. `arrears` usage is invoiced afterwards, so the pool holds no prepaid balance.

**Possible values**: `prepaid` `arrears`

### [status](#get-credit-pool-response-status)

- **Type**: `string`
- **Required**: true

For a prepaid pool: `healthy` means the balance covers the capacity that is running or starting. `grace` means it does not. Capacity beyond what held credit covers cannot be added, and running capacity continues while funding is awaited. `draining` means the grace period has ended, and running capacity may be stopped until what remains fits the balance. `suspended` means a refund took the balance below zero, and no capacity can be added until a top-up brings it back to zero or above. An arrears pool has no prepaid balance to restrict it and reports `healthy`.

**Possible values**: `healthy` `grace` `draining` `suspended`

### [totalBalance](#get-credit-pool-response-totalbalance)

- **Type**: `object (2 properties, nullable)`
- **Required**: true

The prepaid ledger balance, held credit included. Negative when the organization owes credit. `null` for arrears.

#### [amount](#get-credit-pool-response-totalbalance-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

#### [currency](#get-credit-pool-response-totalbalance-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

### [heldCredit](#get-credit-pool-response-heldcredit)

- **Type**: `object (2 properties)`
- **Required**: true

Credit set aside for capacity that is running or starting. It has not been spent, and it is unrelated to reserved capacity.

#### [amount](#get-credit-pool-response-heldcredit-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

#### [currency](#get-credit-pool-response-heldcredit-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

### [availableBalance](#get-credit-pool-response-availablebalance)

- **Type**: `object (2 properties, nullable)`
- **Required**: true

`totalBalance` minus `heldCredit`: the credit left to spend. Can be negative. `null` for arrears.

#### [amount](#get-credit-pool-response-availablebalance-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

#### [currency](#get-credit-pool-response-availablebalance-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

### [observedAt](#get-credit-pool-response-observedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

When these figures were read.

### [Errors](#get-credit-pool-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Serverless billing is not active for the organization yet</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Reserved capacity

GETapi.serverless.runware.ai/v1/reserved-capacity

What the authenticated organization has reserved, what it is using of it now, and what overflowed to pay-as-you-go. One entry per commitment scope, one GPU type in one region, because compatible terms add together and cover an allocation between them. The terms that make up the scope are listed with their own dates and quantities. Counts describe recorded billable state at the window end, so a report of a past period describes that period rather than mixing it with the present. A scope with an effective commitment appears even when nothing is using it: an idle reservation is still charged for, and is what the customer most needs to see. Scopes whose terms expired during the period remain with their historical usage and zero committed capacity at the window end. The fixed commitment charge is not here. Serverless meters usage and does not own that charge. The commerce system invoices it from the contract schedule. Usage that cannot be priced returns `500`, with no partial report.

> [!NOTE]
> A scope with an effective commitment is reported even when nothing is using it, because an idle reservation is still charged for. The fixed commitment charge itself is billed separately and does not appear in this response.

### [Request](#list-reserved-capacity-request)

Query

### [from](#list-reserved-capacity-query-from)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Inclusive lower bound of the reporting period (RFC 3339). Defaults to 24 hours before `to`. The maximum window is 31 days. An explicit zero timestamp (`0001-01-01T00:00:00Z`) returns `422` rather than selecting the default.

### [to](#list-reserved-capacity-query-to)

- **Type**: `string (date-time)`
- **Format**: `date-time`

Exclusive upper bound of the reporting period (RFC 3339). Defaults to now, and a value in the future is read as now. An explicit zero timestamp (`0001-01-01T00:00:00Z`) returns `422` rather than selecting the default.

### [Response](#list-reserved-capacity-response)

### [data](#list-reserved-capacity-response-data)

- **Type**: `object[] (22 properties)`
- **Required**: true

#### [gpuType](#list-reserved-capacity-response-data-gputype)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `64`

Public catalog code for a supported GPU type (e.g. `h100`, `rtx-pro-6000`). Must match an `id` returned by `GET /v1/gpu-types` (validated at request time against the catalog). This is not the internal database row UUID.

#### [region](#list-reserved-capacity-response-data-region)

- **Type**: `string`
- **Required**: true

The region a capacity commitment applies to. One value until app placement selects a region.

**Possible values**: `default`

#### [terms](#list-reserved-capacity-response-data-terms)

- **Type**: `object[] (4 properties)`
- **Required**: true

##### [id](#list-reserved-capacity-response-data-terms-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

##### [gpuCount](#list-reserved-capacity-response-data-terms-gpucount)

- **Type**: `integer`
- **Required**: true
- **Format**: `int32`
- **Min**: `1`

Concurrent GPUs this term reserves.

##### [startsAt](#list-reserved-capacity-response-data-terms-startsat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

Inclusive start of the term.

##### [endsAt](#list-reserved-capacity-response-data-terms-endsat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

Exclusive end of the term. An amended term ends where its replacement starts, so the two never both apply.

#### [committedGpuCount](#list-reserved-capacity-response-data-committedgpucount)

- **Type**: `integer`
- **Required**: true
- **Format**: `int32`
- **Min**: `0`

Concurrent GPUs reserved at `calculatedAt`, across every effective term.

#### [coveredGpuCount](#list-reserved-capacity-response-data-coveredgpucount)

- **Type**: `integer`
- **Required**: true
- **Format**: `int32`
- **Min**: `0`

Reserved GPUs in use at `calculatedAt`.

#### [unusedGpuCount](#list-reserved-capacity-response-data-unusedgpucount)

- **Type**: `integer`
- **Required**: true
- **Format**: `int32`
- **Min**: `0`

Reserved GPUs idle at `calculatedAt`. Charged for, because reserved capacity is a promise of access rather than a quantity of GPU time.

#### [paygOverflowGpuCount](#list-reserved-capacity-response-data-paygoverflowgpucount)

- **Type**: `integer`
- **Required**: true
- **Format**: `int32`
- **Min**: `0`

Matching GPUs in use at `calculatedAt` above the reserved quantity. These are what a pay-as-you-go charge in this scope can be traced to.

#### [from](#list-reserved-capacity-response-data-from)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

Inclusive start of the reported period, as resolved.

#### [to](#list-reserved-capacity-response-data-to)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

Exclusive end of the reported period, as resolved.

#### [coveredGpuMilliseconds](#list-reserved-capacity-response-data-coveredgpumilliseconds)

- **Type**: `integer`
- **Required**: true
- **Format**: `int64`
- **Min**: `0`

Reserved GPU time used over the period.

#### [paygGpuMilliseconds](#list-reserved-capacity-response-data-payggpumilliseconds)

- **Type**: `integer`
- **Required**: true
- **Format**: `int64`
- **Min**: `0`

GPU time in this scope over the period that the reservation did not cover and pay-as-you-go charged for.

#### [paygSpend](#list-reserved-capacity-response-data-paygspend)

- **Type**: `object (2 properties)`
- **Required**: true

Provisional overflow accrual, excluding finalization rounding and ledger adjustments.

##### [amount](#list-reserved-capacity-response-data-paygspend-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#list-reserved-capacity-response-data-paygspend-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

#### [coveredValue](#list-reserved-capacity-response-data-coveredvalue)

- **Type**: `object (2 properties)`
- **Required**: true

The covered time priced at the catalog rate. What pay-as-you-go would have charged for it, and so what the reservation saved.

##### [amount](#list-reserved-capacity-response-data-coveredvalue-amount)

- **Type**: `string`
- **Required**: true

Amount in major units as an exact decimal string.

##### [currency](#list-reserved-capacity-response-data-coveredvalue-currency)

- **Type**: `string`
- **Required**: true

ISO 4217 alphabetic code. The platform bills in USD only.

**Possible values**: `USD`

#### [calculatedAt](#list-reserved-capacity-response-data-calculatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

The instant the counts describe.

### [Errors](#list-reserved-capacity-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>