# Get usage

> Tokens this month and storage.

`GET https://api.codebuckets.clatterlabs.xyz/v1/usage` (key permission: `buckets:read`)

Your Code Buckets plan, this month's tokens and your storage. Also works with a key that has only `account:read`.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA`. Find it in Console › Settings. A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.

## Response

- `object` (string): `usage`.
- `plan` (string): `Free`, or unlimited for Clatter Labs team accounts.
- `period` (object): `{ month }`, like `2026-10` (UTC).
- `tokens` (object): `{ used, included, unit }`. `included` is 1,000,000 on Free.
- `storage` (object): `{ projects, buckets, stored_bytes, bucket_limit_bytes, backups_used, backups_included, public_files }`. `public_files` is this month's traffic to your public links: `{ month, requests, bytes, tokens }`.

## Example request

```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/usage" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `403` | `insufficient_scope` | The key needs `buckets:read` or `account:read`. |

## Example response

```json
{
  "object": "usage",
  "plan": "Free",
  "period": {
    "month": "2026-10"
  },
  "tokens": {
    "used": 1342,
    "included": 1000000,
    "unit": "1 per request + 1 per MiB uploaded or downloaded"
  },
  "storage": {
    "projects": 1,
    "buckets": 1,
    "stored_bytes": 131204115,
    "bucket_limit_bytes": 10737418240,
    "backups_used": 1,
    "backups_included": 1,
    "public_files": {
      "month": "2026-10",
      "requests": 1840,
      "bytes": 96468992,
      "tokens": 1932
    }
  }
}
```