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

# Get Usage Stats

> Get request usage statistics and budget info for your API key

Returns your API key's request counts and monthly credit consumption. Use this to monitor how close you are to your credit limit, track usage trends, or build self-budgeting logic into your integration. This endpoint does not consume monthly credit budget.

This route is also the safest place to inspect the packaging metadata attached to your key and request path. The response headers include:

* `X-Plan-Tier`
* `X-Api-Surface`
* `X-Access-Layer`
* `X-Endpoint-Policy`
* `X-Credit-Cost`

## Query Parameters

None. Usage is determined by the API key in your Authorization header.

### Request

```bash cURL theme={null}
curl -X GET "https://api.shoal.xyz/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200)

```json theme={null}
{
  "data": {
    "today": 42,
    "thisWeek": 310,
    "thisMonth": 1205,
    "budget": {
      "limit": 1000,
      "used": 420,
      "remaining": 580
    }
  }
}
```

| Field              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `today`            | Requests made since midnight UTC today             |
| `thisWeek`         | Requests made since the start of the current week  |
| `thisMonth`        | Requests made since the start of the current month |
| `budget.limit`     | Monthly credit budget for the API key              |
| `budget.used`      | Credits consumed so far this month                 |
| `budget.remaining` | Credits remaining for the current month            |

<Note>
  The request counters (`today`, `thisWeek`, `thisMonth`) track request volume. The `budget` object tracks monthly credit consumption.
</Note>

<Note>
  `/v1/usage` itself is an `evaluation`-layer `usage` surface and does not consume monthly credits.
</Note>