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

# Usage

> Inspect current billing cycle credit consumption and request counts.

Returns the current billing cycle credit summary for your org. Requires the `control:read` scope.

## Get usage

```
GET https://api.usehasp.com/v1/usage
Authorization: Bearer hasp_api_live_...
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "period": {
      "start": "2026-05-01T00:00:00+00:00",
      "end": null
    },
    "credits": {
      "allotment": 100000,
      "used": 37420,
      "remaining": 62580,
      "overage_purchased": 0,
      "overage_consumed": 0
    },
    "requests": {
      "total": 841
    }
  }
}
```

### Fields

| Field                       | Description                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| `period.start`              | Start of the current billing cycle (ISO 8601).                                                            |
| `period.end`                | End of the current billing cycle, or `null` if open-ended.                                                |
| `credits.allotment`         | Total credits available this cycle (base plan + any overages purchased).                                  |
| `credits.used`              | Credits consumed so far this cycle. Sonnet-equivalent tokens: Haiku requests count as 0.3×, Opus as 1.7×. |
| `credits.remaining`         | `allotment - used`. Requests fail with `402 AI_CREDITS_EXHAUSTED` when this reaches zero.                 |
| `credits.overage_purchased` | Additional credits purchased outside the plan allotment.                                                  |
| `credits.overage_consumed`  | Overage credits consumed.                                                                                 |
| `requests.total`            | Total AI requests made this cycle.                                                                        |

### Credit accounting

Credits are denominated in Sonnet-equivalent tokens. The model rate-ratios are:

| Model               | Rate-ratio |
| ------------------- | ---------- |
| `claude-haiku-4-5`  | 0.3×       |
| `claude-sonnet-4-6` | 1.0×       |
| `claude-opus-4-7`   | 1.7×       |

A 100-token Haiku response consumes \~30 credits; a 100-token Opus response consumes \~170 credits. The `meta.usage.sonnet_equivalent_tokens` field on every AI response shows the credit impact of that specific request.

## Error codes

| Code              | HTTP | Description                    |
| ----------------- | ---- | ------------------------------ |
| `INVALID_API_KEY` | 401  | Invalid or revoked token       |
| `MISSING_SCOPE`   | 403  | Key lacks `control:read` scope |