# Read swarm cost and token usage

Cost and tokens for the coordinator, each child and the whole swarm. costMicros is what thread usage reports as charged: platform-paid model calls plus billed sandbox time, in USD micros. Tokens are split into uncached input, cache reads, cache writes and output. totalTokens, coordinatorTokens and each child's tokens remain input plus output with cache reads included. Requires a member's session or personal API key; service account keys receive 403 user_identity_required.

`GET /api/swarms/{id}/usage`

Required permission: `thread:read`.

## Parameters

| Name | In | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes | — |

## Example request

```bash
curl --request GET \
  --url https://api.hoplite.sh/api/swarms/id/usage \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

## 200 response

Successful response

Content type: `application/json`. Response type: `object`.

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| `totalTokens` | `number` | Yes | min 0 | — |
| `coordinatorTokens` | `number` | Yes | min 0 | — |
| `coordinator` | `object` | Yes | — | — |
| `coordinator.costMicros` | `number` | Yes | min 0 | — |
| `coordinator.llmCostMicros` | `number` | Yes | min 0 | — |
| `coordinator.vmCostMicros` | `number` | Yes | min 0 | — |
| `coordinator.uncachedInputTokens` | `number` | Yes | min 0 | — |
| `coordinator.cacheReadTokens` | `number` | Yes | min 0 | — |
| `coordinator.cacheWriteTokens` | `number` | Yes | min 0 | — |
| `coordinator.outputTokens` | `number` | Yes | min 0 | — |
| `total` | `object` | Yes | — | — |
| `total.costMicros` | `number` | Yes | min 0 | — |
| `total.llmCostMicros` | `number` | Yes | min 0 | — |
| `total.vmCostMicros` | `number` | Yes | min 0 | — |
| `total.uncachedInputTokens` | `number` | Yes | min 0 | — |
| `total.cacheReadTokens` | `number` | Yes | min 0 | — |
| `total.cacheWriteTokens` | `number` | Yes | min 0 | — |
| `total.outputTokens` | `number` | Yes | min 0 | — |
| `children` | `object[]` | Yes | — | — |
| `children.costMicros` | `number` | Yes | min 0 | — |
| `children.llmCostMicros` | `number` | Yes | min 0 | — |
| `children.vmCostMicros` | `number` | Yes | min 0 | — |
| `children.uncachedInputTokens` | `number` | Yes | min 0 | — |
| `children.cacheReadTokens` | `number` | Yes | min 0 | — |
| `children.cacheWriteTokens` | `number` | Yes | min 0 | — |
| `children.outputTokens` | `number` | Yes | min 0 | — |
| `children.threadId` | `string` | Yes | — | — |
| `children.tokens` | `number` | Yes | min 0 | — |
| `ok` | `boolean` | Yes | constant true | — |

```json

```

## Response headers

| Header | Type | Statuses | Description |

| --- | --- | --- | --- |

| `RateLimit` | `string` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Current ingress policy, remaining requests, and seconds until reset, for example `"ingress";r=599;t=60`. |

| `RateLimit-Policy` | `string` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Ingress quota and window, for example `"ingress";q=600;qu="requests";w=60`. |

| `X-RateLimit-Limit` | `integer` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Maximum requests allowed in the current rolling window. |

| `X-RateLimit-Remaining` | `integer` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Requests remaining in the current rolling window. |

| `X-RateLimit-Reset` | `integer` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Unix timestamp when the current rolling window resets. |

| `x-request-id` | `string` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Request correlation ID. |

| `Retry-After` | `integer` | `429`, `503` | Seconds until another request should be attempted. |

| `X-Retry-After` | `integer` | `429`, `503` | Legacy retry delay in seconds. |

## Status codes

- `200` — Successful response

- `400` — Invalid request. Validation responses include field paths.

- `401` — The API key is missing, invalid, or lacks the operation's permission.

- `402` — The organization does not have access to the requested product capability.

- `403` — The key's current user no longer has the required organization membership or role.

- `404` — The resource is not available in the authenticated scope.

- `409` — The request conflicts with a retry receipt or current resource state.

- `410` — The event cursor has expired; capture a fresh head and resource snapshot.

- `429` — The API-key rate limit has been exceeded.

- `500` — The API encountered an unexpected failure.

- `501` — The deployment has not configured the requested capability.

- `503` — A required API dependency, including the rate limiter, is unavailable.