# Current-period usage against the plan allowance

> Usage for the current period, with credit allowance arithmetic in micro-credits (1 credit = 1000000), plus the monthly allowance the API enforces.

Source: https://docs.spicrawl.com/api-reference/usage/usage-summary

## GET /v1/usage/summary

Operation ID: `usageSummary`. API key scope: `read`.

Usage for the current period, with credit allowance arithmetic in micro-credits (1 credit =
1000000), plus the monthly allowance the API enforces. Takes no parameters.

Every organization has a monthly credit allowance (1,000 credits unless an operator set a
different limit for the organization), counted per allowance month: from 00:00 UTC on the day of
the month the organization was created to the same day of the next month. When it is used up,
requests are refused with 402 `ERR::LIMIT::QUOTA_EXCEEDED` until `allowance.resets_at`.

- `allowance` is the number the API enforces, and the one to show as "credits left":
  `allowance.remaining_micro`. Its `used_micro` is the enforcement counter, which includes
  credits currently HELD for in-flight work (an open browser session holds its whole
  `session_ttl` price, a batch job holds the price of its unfinished items) as well as credits
  spent. It is omitted when the deployment has no allowance counter, or when the counter could
  not be read (a warning then says so).
- `credits` is METERED usage from the usage rollup for the period: spent credits only, batch
  items included, but not credits held for work still running. It can therefore be lower than
  `allowance.used_micro`.
- With no subscription (the usual case), the organization is on the free plan: `plan` names the
  current `free` plan, `plan.subscription_status` is `none`, `plan.period_source` is
  `allowance_month`, and `credits.included_micro` is the enforced monthly limit. The period is
  the allowance month, not a billing period.
- With a subscription, `period_source` is `subscription`, the period is the billing period and
  `credits.included_micro` is the plan's included credits. The enforced limit is still
  `allowance.limit_micro`.

Pitfalls:
- There is no money figure. Overage pricing is computed only at invoicing.
- `unattributed` usually equals `metrics` today because per-engine attribution is not populated.

### Example

```bash
curl "https://api.spicrawl.com/v1/usage/summary" \
  -H "Authorization: Bearer $SPICRAWL_API_KEY"
```

### Responses

#### 200

The summary.

`application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `period` | object (`UsagePeriod`) | yes | Half-open range of UTC days. |
| `period_elapsed_days` | integer | yes | Whole days of the period elapsed, clamped to [0, period.days]. Use it to pace consumption. |
| `plan` | object (`UsagePlan`) | yes |  |
| `credits` |  | yes | Metered usage against the plan's included credits, or, with no subscription, against the enforced monthly limit. Filled for every organization (the type stays nullable because older servers returned null when there was no subscription). Includes batch spend but not credits held for in-flight work; show `allowance` as "credits left". |
| `allowance` | object (`UsageAllowance`) | no | The monthly credit allowance as the API ENFORCES it, for the current allowance month. This is the number that decides whether the next request is refused with 402 `ERR::LIMIT::QUOTA_EXCEEDED`, and the one to show as "credits left". Present for every organization, subscribed or not; omitted only when the deployment has no allowance counter or it could not be read (a warning then says so). |
| `metrics` |  | yes | Every billed metric for the period. |
| `unattributed` |  | yes | Part of each metric that per-engine attribution does not explain. Usually equals `metrics` today. |
| `usage_as_of` | string \| null (date-time) | yes | Newest rollup row in the period, or null when none. |
| `stale_seconds` | integer \| null | yes | Age of `usage_as_of` in seconds; null when no rows. |
| `warnings` | array of string | no | Caveats, e.g. that the allowance counter could not be read. Omitted when empty. |

Example `subscribed`

```json
{
  "period": {
    "start": "2026-09-01",
    "end": "2026-10-01",
    "days": 30,
    "bounds": "[start, end)"
  },
  "period_elapsed_days": 21,
  "plan": {
    "code": "growth",
    "name": "Growth",
    "version": 3,
    "subscription_status": "active",
    "period_source": "subscription"
  },
  "credits": {
    "included_micro": 100000000000,
    "used_micro": 42500000000,
    "remaining_micro": 57500000000,
    "overage_micro": 0,
    "overage_micro_cents_per_credit": 90000,
    "used_basis_points": 4250
  },
  "allowance": {
    "limit_micro": 1000000000,
    "limit_credits": 1000,
    "limit_source": "default",
    "unlimited": false,
    "used_micro": 430000000,
    "remaining_micro": 570000000,
    "window_start": "2026-09-14T00:00:00Z",
    "resets_at": "2026-10-14T00:00:00Z"
  },
  "metrics": {
    "requests": 10630,
    "credits": 42500000000,
    "engine_ms": 18200000
  },
  "unattributed": {
    "requests": 10630,
    "credits": 42500000000,
    "engine_ms": 18200000
  },
  "usage_as_of": "2026-09-22T11:55:00Z",
  "stale_seconds": 300
}
```

Example `no_subscription`: No subscription (the free allowance)

```json
{
  "period": {
    "start": "2026-09-14",
    "end": "2026-10-14",
    "days": 30,
    "bounds": "[start, end)"
  },
  "period_elapsed_days": 8,
  "plan": {
    "code": "free",
    "name": "Free",
    "version": 1,
    "subscription_status": "none",
    "period_source": "allowance_month"
  },
  "credits": {
    "included_micro": 1000000000,
    "used_micro": 212000000,
    "remaining_micro": 788000000,
    "overage_micro": 0,
    "overage_micro_cents_per_credit": 0,
    "used_basis_points": 2120
  },
  "allowance": {
    "limit_micro": 1000000000,
    "limit_credits": 1000,
    "limit_source": "default",
    "unlimited": false,
    "used_micro": 260000000,
    "remaining_micro": 740000000,
    "window_start": "2026-09-14T00:00:00Z",
    "resets_at": "2026-10-14T00:00:00Z"
  },
  "metrics": {
    "requests": 2410,
    "credits": 212000000
  },
  "unattributed": {
    "requests": 2410,
    "credits": 212000000
  },
  "usage_as_of": "2026-09-22T11:55:00Z",
  "stale_seconds": 300
}
```

#### 401

Missing, invalid, revoked or expired key. Not retryable with the same key.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

#### 403

The key lacks the scope this route requires (`ERR::AUTH::INSUFFICIENT_SCOPE`), or the action is not permitted.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

#### 500

Internal error. Retryable when `retryable` is true.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

Full OpenAPI spec: https://docs.spicrawl.com/openapi.yaml