# Get this month's summary

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

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

The headline numbers for the current UTC month: usage so far, the
month-end projection, what usage so far would cost, and where the
free allowance and payment state stand.

- `mtd_ehu` is the billable usage so far; `projected_ehu` adds the
  run rate of the last seven complete days for the rest of the month.
- `projected_usd` and `charged_usd` are already net of the free
  allowance and of credit — do not subtract them again.
- `charged_usd` breaks down as `allowance_covered_ehu` (absorbed by
  the free allowance), `credit_applied_ehu` (covered by credit) and
  `overage_ehu` (charged to the card), out of `chargeable_ehu`.
- `dispatch_blocked` is `true` when outbound notifications are
  stopped because the allowance is spent and there is neither a card
  nor credit; `dispatch_blocked_at` and `dispatch_block_reason` then
  say since when and why. While notifications are still sent but the
  same condition holds, `dispatch_grace_ends_at` is when they stop.

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_…`).

## Responses

### 200 — The summary.

Content type: `application/json`

Type: `object`

- `data` (Summary)
  - `period_start` (string (date)): The first day of the current month.
  - `period_end` (string (date)): The first day of next month (exclusive).
  - `mtd_ehu` (number): Billable usage so far this month.
  - `usage_ehu` (number): The same usage, summed per line.
  - `projected_ehu` (number): Forecast usage for the whole month.
  - `projected_usd` (number): Forecast charge for the month, net of the free allowance and credit.
  - `days_elapsed` (integer): Complete days the run rate is read from.
  - `days_remaining` (integer)
  - `charged_usd` (number): What usage so far would cost, net of the free allowance and credit.
  - `allowance_covered_ehu` (number)
  - `credit_applied_ehu` (number)
  - `chargeable_ehu` (number): Usage the free allowance did not cover, before credit.
  - `overage_ehu` (number): Usage left to charge to the card after the allowance and credit — the EHU behind `charged_usd`.
  - `commitment_ehu` (number): The committed volume billed this month; 0 without a commitment.
  - `status` (string, one of `active`, `suspended`)
  - `pricing_tier` (string, one of `on_demand`, `commitment`, `prepaid`)
  - `allowance_ehu` (number): This month's free allowance.
  - `allowance_used_ehu` (number)
  - `allowance_remaining_ehu` (number)
  - `has_payment_method` (boolean)
  - `dispatch_blocked` (boolean): Whether outbound notifications are stopped right now.
  - `dispatch_blocked_at` (string (date-time)): Present only while `dispatch_blocked` is `true`.
  - `dispatch_block_reason` (string, value `allowance_spent_no_card_no_credit`): Present only while `dispatch_blocked` is `true`.
  - `dispatch_grace_ends_at` (string (date-time)): When notifications stop if nothing changes. Present only while the allowance is spent with no card and no credit, and notifications are still being sent.

### 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 — The summary could not be computed (`SUMMARY_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/summary' \
  -H 'Authorization: Bearer <TOKEN>'
```