> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AI usage

> GET /api/v1/comms/ai/usage — tokens used this period and pass-through rates.

Read this month's AI token meter. Hosted agent replies and `POST /api/v1/comms/chat/completions` share it.

**Scope:** `comms_ai`

## Request

```bash theme={null}
curl "https://osis.co/api/v1/comms/ai/usage" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

## Response

```json theme={null}
{
  "usage": {
    "periodStart": "2026-08-01",
    "currentPeriodEnd": "2026-09-01T00:00:00.000Z",
    "planKey": "plus",
    "planName": "Plus",
    "usageBilled": false,
    "used": 12840,
    "included": null,
    "remaining": null,
    "rates": {
      "inputUsdPerMillion": 3.5,
      "outputUsdPerMillion": 18
    },
    "models": ["claude-sonnet-5"]
  }
}
```

| Field         | Meaning                                                                   |
| ------------- | ------------------------------------------------------------------------- |
| `used`        | Tokens counted this period (prompt + completion)                          |
| `included`    | Always `null` — no plan includes AI tokens                                |
| `remaining`   | Always `null` — usage is billed, not capped                               |
| `usageBilled` | `true` on the Messaging Services Agreement — usage is invoiced in arrears |
| `rates`       | Pass-through USD per million tokens                                       |

## Models

```bash theme={null}
curl "https://osis.co/api/v1/comms/ai/models" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5",
      "object": "model",
      "created": 0,
      "owned_by": "comms",
      "default": true
    }
  ]
}
```

**Scope:** `comms_ai`

## Related

* [Chat completions](/messages-api/chat-completions)
* [Pass-through AI](/guides/pass-through-ai)