---
title: "Usage and credit: balance, holds, free usage, startup hours, a pilot's sandbox-hours and per-resource charges, in integer microdollars."
method: GET
path: "/v1/usage"
tags: ["account"]
---

# Usage and credit: balance, holds, free usage, startup hours, a pilot's sandbox-hours and per-resource charges, in integer microdollars.

`GET /v1/usage`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/usage`
- Auth: HTTP bearer

## Query parameters

- `key` string: A key's id (POST /v1/keys and GET /v1/keys give it): adds that key's own spend as `key`. A key reads itself, the keys it made, and any key its reads reach.

## Response `200`

Success

- object
  - `orgId` string
  - `unit` 'microdollars', required
  - `credited` string, required: Every credit ever added: purchases and grants. Integer microdollars, as a string.
  - `spent` string, required: Settled usage, including what refunds and disputes took back. Integer microdollars, as a string.
  - `held` string, required: Reserved against running and paused work, not yet settled. Integer microdollars, as a string.
  - `expired` string, required: Credit that expired, or grant credit taken back. Integer microdollars, as a string.
  - `available` string, required: What can still be spent: credited - spent - expired - held. Integer microdollars, as a string.
  - `takenBack` string, required: The part of spent that refunds and disputes took. Integer microdollars, as a string.
  - `trial` object, nullable: Machine time an account without credit can still run, in milliseconds, or null when the account has none. GET /v1/limits describes each field.
    - `totalMs` integer
    - `usedMs` integer
    - `reservedMs` integer
    - `availableMs` integer
    - `offer` 'hours' | 'monthly'
    - `renewsAt` string, date-time
  - `outbound` object, nullable: Outbound traffic this calendar month (UTC): bytes the account's sandboxes sent to the internet, the part the monthly free usage covered, the part charged at the quoted rate, and what that cost.
    - `month` string: The month, YYYY-MM.
    - `sentBytes` integer
    - `freeBytes` integer
    - `billableBytes` integer
    - `allowanceBytes` integer
    - `chargedMicros` string: Charged for outbound traffic this month. Integer microdollars, as a string.
    - `writtenOffMicros` string: Owed for outbound traffic this month but not charged, because credit or a spending limit ran out. Integer microdollars, as a string.
  - `allowances` object[]: What the account uses free, drawn before credit and never charged. With no credit, a product whose free usage is used is refused (included_usage_used_up) and its running sandboxes pause, until the 1st (an account that has paid) or until credit is added.
    - `pool` string: machine-memory, machine-cpu, saved-copies (snapshots, images, backups) or disks (volumes).
    - `unit` string: GiB-hour, vCPU-hour or GB-month.
    - `quantity` number: What the month allows, in unit.
    - `used` number: Used by what has settled this month.
    - `reserved` number: Held for what is running now; given back unless used.
    - `left` number: Left this month: quantity less used. What is reserved is not taken off.
    - `month` string: The month's first day, YYYY-MM-DD (UTC).
    - `renewsAt` string: When the next month's free usage starts, ISO 8601 UTC.
    - `freeUntil` string, nullable: When the free machine time ends for an account that has never paid: 30 days after it opened, ISO 8601 UTC. Null once the account has paid, when it renews every month.
  - `startupIncluded` object[]: What Runtime for Startups includes: empty unless the account was accepted to it or given it. Machine time (startup hours) is given once, used after this month's free usage and before credit, never renewed, and gone after 12 months; storage is GB kept free each month for those 12 months.
    - `pool` string: machine-cpu, machine-memory, saved-copies (snapshots, images and backups) or disks (volumes).
    - `unit` string: vCPU-hour or GiB-hour for startup hours given once; GB for storage kept free each month.
    - `period` string: once: a quantity given once and used up by what runs (machine-cpu, machine-memory). month: quantity GB added to each month's included storage until expiresAt, never used up; storage past it bills at the published rate (saved-copies, disks).
    - `quantity` number: What Runtime for Startups includes, in unit: once for machine time, or each month for storage.
    - `used` number, nullable: Used by what has settled; null for monthly storage.
    - `reserved` number, nullable: Held for what is running now; given back unless used. Null for monthly storage.
    - `left` number, nullable: Left: quantity less used. What is reserved is not taken off. Null for monthly storage.
    - `keptGB` number, nullable: Storage kept now (decimal GB); null for startup hours given once.
    - `source` string: startup: the account was accepted to Runtime for Startups.
    - `grantedAt` string: When it was given, ISO 8601 UTC.
    - `expiresAt` string: 12 months after grantedAt, ISO 8601 UTC: what is left then is gone.
  - `startupLimits` object, nullable: What Runtime for Startups includes at once for its 12 months, or null without it or after them, when the account's own limits apply: image builds, and sandboxes (past it, a create answers quota_exceeded).
    - `buildsAtOnce` integer, required
    - `sandboxesAtOnce` integer, required
  - `pot` object[]: Renamed startupIncluded; works until 30 days after the rename ships (date set at deploy), then is gone.
    - `pool` string: machine-cpu, machine-memory, saved-copies (snapshots, images and backups) or disks (volumes).
    - `unit` string: vCPU-hour or GiB-hour for startup hours given once; GB for storage kept free each month.
    - `period` string: once: a quantity given once and used up by what runs (machine-cpu, machine-memory). month: quantity GB added to each month's included storage until expiresAt, never used up; storage past it bills at the published rate (saved-copies, disks).
    - `quantity` number: What Runtime for Startups includes, in unit: once for machine time, or each month for storage.
    - `used` number, nullable: Used by what has settled; null for monthly storage.
    - `reserved` number, nullable: Held for what is running now; given back unless used. Null for monthly storage.
    - `left` number, nullable: Left: quantity less used. What is reserved is not taken off. Null for monthly storage.
    - `keptGB` number, nullable: Storage kept now (decimal GB); null for startup hours given once.
    - `source` string: startup: the account was accepted to Runtime for Startups.
    - `grantedAt` string: When it was given, ISO 8601 UTC.
    - `expiresAt` string: 12 months after grantedAt, ISO 8601 UTC: what is left then is gone.
  - `potLimits` object, nullable: Renamed startupLimits; works until 30 days after the rename ships (date set at deploy), then is gone.
    - `buildsAtOnce` integer, required
    - `sandboxesAtOnce` integer, required
  - `pilot` object, nullable: The account's pilot, while it serves its sandboxes, or null: a pilot is a free run agreed with Runtime. hours is its included time in sandbox-hours (running time of every pilot sandbox, whatever its size; paused and stopped time does not count); usedMs and leftMs are that time used and left, in milliseconds. Once it is used, its running sandboxes pause with their memory kept, and creates and wakes answer pilot_hours_used; to extend the pilot or ask for more hours, the account's owner writes to support.
    - `id` string
    - `sandboxes` integer
    - `vcpu` integer
    - `memoryMiB` integer
    - `diskMiB` integer
    - `startsAt` string
    - `endsAt` string: New pilot sandboxes until then, ISO 8601 UTC.
    - `graceEndsAt` string: The pilot's sandboxes are served, free, until then, ISO 8601 UTC.
    - `endedAt` string, nullable
    - `hours` integer
    - `usedMs` integer
    - `leftMs` integer
    - `running` integer: Its sandboxes starting, running or resuming now, each using one sandbox-hour per hour: leftMs / running is how long the hours last at this rate.
  - `key` object: With ?key=<key id> only: that key's own spend, so a coordinator sees which worker spent what. A key may read itself, the keys it made (POST /v1/keys) at any depth, and any key whose agent its reads already reach (an account-wide or read-only key's).
    - `keyId` string, required
    - `agentId` string, required: The key's agent: what it made and spent is this agent's.
    - `name` string, required
    - `madeBy` string, nullable, required: The key that made it, if a key did.
    - `revokedAt` string, nullable, required
    - `dailyLimitMicros` string, nullable, required: Its daily limit, in integer microdollars as a string, or null for none.
    - `dailyUsedMicros` string, required: What it committed in the last 24 hours, as its daily limit counts: settled plus held. Integer microdollars, as a string.
    - `spentMicros` string, required: Everything it has spent, settled. Integer microdollars, as a string.
    - `heldMicros` string, required: What its running work holds now; settled as it is used. Integer microdollars, as a string.
    - `runningSandboxes` integer, required
    - `resources` integer, required: What it made that is not deleted: sandboxes, snapshots, volumes, images.
  - `kinds` object[]: Everything this principal acts for, one row a kind, however many: how many resources, what was charged and what is held.
    - `kind` string, required
    - `resources` integer, required
    - `chargedMicros` string, required: What its settled windows charged. Integer microdollars, as a string.
    - `heldMicros` string, required: What its open windows hold. Integer microdollars, as a string.
  - `resources` object[], required: This principal's hundred newest resources and what each has used and been charged; kinds totals all of them.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)