--- 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. > [!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: it cannot be changed after creation, and it becomes available again once the app it named reaches `deleted`. ### [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[] (11 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: it cannot be changed after creation, and it becomes available again once the app it named reaches `deleted`. #### [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)
StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
422The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns 400. The errors array carries one entry per offending field.
500Unexpected server error
503A required service is temporarily unavailable
## Summarize usage GETapi.serverless.runware.ai/v1/usage/summary GPU time and spend for the authenticated organization, aggregated over a half-open window and grouped by the dimensions asked for. 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 saved. Time covered by a capacity commitment 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 saved. ### [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 window is 31 days. 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. A filter on what is reported, not on what is measured: coverage depends on every app's concurrent GPUs. ### [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. Each dimension appears on the bucket it was requested with and is absent otherwise. ### [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[] (11 properties)` - **Required**: true #### [appId](#get-usage-summary-response-buckets-appid) - **Type**: `string` - **Min**: `6` - **Max**: `30` Present when grouped by `app`. #### [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` UTC calendar day. Present when grouped by `day`. A span crossing midnight is divided between the two days it ran on. #### [coverage](#get-usage-summary-response-buckets-coverage) - **Type**: `string` Present when grouped by `coverage`. **Possible values**: `commitment` `payg` #### [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 that crosses midnight is divided so that its days 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 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. ##### [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 (11 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`. #### [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` UTC calendar day. Present when grouped by `day`. A span crossing midnight is divided between the two days it ran on. #### [coverage](#get-usage-summary-response-total-coverage) - **Type**: `string` Present when grouped by `coverage`. **Possible values**: `commitment` `payg` #### [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 that crosses midnight is divided so that its days 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 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. ##### [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)
StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
422The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns 400. The errors array carries one entry per offending field.
500Unexpected server error
503A required service is temporarily unavailable
## 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)
StatusWhen
401Missing or invalid credentials
404Serverless billing is not active for the organization yet
500Unexpected server error
503A required service is temporarily unavailable
## 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. #### [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)
StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
422The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns 400. The errors array carries one entry per offending field.
500Unexpected server error
503A required service is temporarily unavailable