# API reference — Account

Usage, budgets, keys, and receipted data deletion.

## GET /v1/usage

Get usage for a period

Robot-hours by tier, environment-hours by class, and dollars, for the given billing period.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| period | query | `string` | yes |  |

Example response (200):

```json
{
 "object": "usage",
 "period": "2026-09",
 "robot_hours": {
  "verify": 141.2,
  "soak": 2210.5
 },
 "env_hours": {
  "bare": 96,
  "standard": 402.3,
  "replica": 118.9,
  "instrumented-replica": 6.2
 },
 "usd_total": 18940,
 "budget": {
  "monthly_usd": 25000,
  "hard": true,
  "remaining_usd": 6060
 }
}
```

## PUT /v1/budgets

Set the monthly budget

With `hard: true`, new work is rejected and running work is stopped at the cap (`monthly_budget_exceeded`). Metered live.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| monthly_usd | body | `number` | yes |  |
| hard | body | `boolean` | no | Hard stop: reject new work and stop running work at the cap. |
| remaining_usd | body | `number` | no |  |

Example request:

```json
{
 "monthly_usd": 25000,
 "hard": true
}
```

Example response (200):

```json
{
 "monthly_usd": 25000,
 "hard": true
}
```

## POST /v1/keys

Create an API key

Keys are scoped (e.g. `runs:write`, `streams:read`, `data:purge`). The secret (`rbr_live_` prefix) is shown once at creation.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| scope | body | `array<runs:read \| runs:write \| streams:read \| data:purge \| keys:admin \| calibration:export>` | yes |  |

Example request:

```json
{
 "scope": [
  "runs:write",
  "streams:read"
 ]
}
```

Example response (201):

```json
{
 "object": "key",
 "id": "key_51ab",
 "scope": [
  "runs:write",
  "streams:read"
 ],
 "secret": "rbr_live_4eC39HqLyjWDarjtT1zdp7dc",
 "created": "2026-09-01T12:00:00Z"
}
```

## GET /v1/keys

List API keys

Lists keys for the account. Secrets are never returned after creation.

Example response (200):

```json
{
 "object": "list",
 "data": [
  {
   "object": "key",
   "id": "key_51ab",
   "scope": [
    "runs:write",
    "streams:read"
   ],
   "created": "2026-09-01T12:00:00Z"
  }
 ]
}
```

## DELETE /v1/data/{run_id}

Purge run data (receipted)

Customer-initiated deletion of all artifacts for a run. Returns a deletion receipt. Requires the `data:purge` scope.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| run_id | path | `string` | yes |  |

Example response (200):

```json
{
 "object": "purge_receipt",
 "id": "prg_77c2",
 "run_id": "run_8842",
 "status": "completed",
 "purged_at": "2026-09-01T13:14:00Z"
}
```