# Get itemised usage

`GET https://evohub.io/api/v1/billing/usage`

Part of the [Billing API](https://docs.evohub.io/billing.md) reference · operationId `getUsage`.

Usage per metric over a date range — by default the current UTC
month. `from` is inclusive and `to` is exclusive, so
`from=2026-10-01&to=2026-11-01` is October.

With `group_by=day`, the answer has one entry per day that has
usage, oldest first, each with its total EHU and its metrics.
Otherwise it has one row per metric for the whole range.

Requires the `billing:usage:read` scope.

## Authorization

Any one of:

- `bearerKey`
- `headerKey`

Where:

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Query parameters

- `from` (string (date), example `2026-10-01`): First day, `YYYY-MM-DD`. Default the first day of the current month.
- `to` (string (date), example `2026-11-01`): The day after the last one, `YYYY-MM-DD`. Default the first day of next month.
- `group_by` (string, one of `metric`, `day`): `day` for a per-day breakdown; anything else (or nothing) totals per metric.

## Responses

### 200 — The usage.

Content type: `application/json`

Type: `object`

- `data` (UsageByMetric | UsageByDay)
  - One of:
    - UsageByMetric
      - `from` (string (date))
      - `to` (string (date))
      - `metrics` (array of UsageRow)
        - `metric_key` (string, example `oncall.alert_ingested`)
        - `quantity` (number): How many of the metric's units were used.
        - `ehu` (number): Their EHU, exact.
    - UsageByDay
      - `from` (string (date))
      - `to` (string (date))
      - `days` (array of object)
        - `day` (string (date))
        - `ehu` (number)
        - `metrics` (array of UsageRow)
          - `metric_key` (string, example `oncall.alert_ingested`)
          - `quantity` (number): How many of the metric's units were used.
          - `ehu` (number): Their EHU, exact.

### 400 — `from` or `to` is not `YYYY-MM-DD` (`INVALID_FROM`, `INVALID_TO`), or `to` is not after `from` (`INVALID_RANGE`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 429 — Too many requests (`RATE_LIMITED`). Wait for `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait before retrying.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 500 — Usage could not be loaded (`USAGE_FAILED`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

## Example request

```bash
curl -X GET 'https://evohub.io/api/v1/billing/usage' \
  -H 'Authorization: Bearer <TOKEN>'
```