# Usage API

> Device-minutes used over a time range, per day and per device, exact up to the current minute.

Source: https://akaphone-docs.pages.dev/api/usage/

## Get usage

`GET /v1/usage`

Returns the device-minutes charged in a time range, in total, per UTC day and per device. Minutes still in the current 10-minute window of a running device are included, so the numbers are exact at the moment you ask.

| Query | Type | Default | Description |
|---|---|---|---|
| `from` | ISO 8601 time or Unix milliseconds | Start of the current month (UTC) | Inclusive. |
| `to` | ISO 8601 time or Unix milliseconds | Now | Exclusive. |

```bash title="curl"
curl "https://akaphone.abhgnx-417.workers.dev/v1/usage?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $AKAPHONE_API_KEY"
```
```typescript title="TypeScript"
const params = new URLSearchParams({ from: "2026-10-01T00:00:00Z", to: "2026-11-01T00:00:00Z" });
const usage = await fetch(`https://akaphone.abhgnx-417.workers.dev/v1/usage?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AKAPHONE_API_KEY}` },
}).then((r) => r.json());
console.log(`${usage.total_minutes} minutes this month`);
```
```python title="Python"
import os, requests

usage = requests.get(
    "https://akaphone.abhgnx-417.workers.dev/v1/usage",
    params={"from": "2026-10-01T00:00:00Z", "to": "2026-11-01T00:00:00Z"},
    headers={"Authorization": f"Bearer {os.environ['AKAPHONE_API_KEY']}"},
).json()
```

**Response** `200 OK`

```json
{
  "from": "2026-10-01T00:00:00.000Z",
  "to": "2026-10-26T09:40:12.000Z",
  "total_minutes": 143,
  "active_devices": 1,
  "by_day": [
    { "date": "2026-10-20", "minutes": 41 },
    { "date": "2026-10-25", "minutes": 74 },
    { "date": "2026-10-26", "minutes": 28 }
  ],
  "devices": [
    { "device_id": "dev_ynxe87v87zx0", "minutes": 74, "status": "terminated", "name": null },
    { "device_id": "dev_qj196bgdqs10", "minutes": 41, "status": "terminated", "name": "run-1842" },
    { "device_id": "dev_s6zr7mr4f2f1", "minutes": 28, "status": "running", "name": "checkout-test" }
  ]
}
```

| Field | Description |
|---|---|
| `from`, `to` | The range used. `to` is capped at the current time. |
| `total_minutes` | Sum of `by_day`. |
| `active_devices` | Devices in `devices` that are running now. |
| `by_day` | Minutes per UTC day, oldest first. Days with no usage are omitted. |
| `devices` | Minutes per device in the range, most first, with its current `status` and `name`. |

`400 invalid_request` if `from` or `to` cannot be parsed.

> **Usage is recorded in windows**
>
> Minutes are charged one at a time but written to the ledger once per device per 10-minute window, dated at the end of the window. A device that ran across midnight UTC may have its minutes counted on the later day. Usage older than 90 days is combined into one row per month; for those months `devices` is empty and `by_day` shows the month's total on its first day.

Your balance and the minutes used this calendar month are also in [`GET /v1/me`](https://akaphone-docs.pages.dev/api/me/).