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

# Usage and quotas

> Understand how Operational Evidence usage is counted and how monthly quota enforcement works.

# Usage and quotas

Operational Evidence tracks usage by customer and operation.

The current operation identifier is:

```text theme={null}
evidence_report
```

## Usage unit

Each successfully completed Evidence Report consumes:

```text theme={null}
1 evidence_report unit
```

A successful response includes the usage associated with that report:

```json theme={null}
{
  "usage": {
    "operation": "evidence_report",
    "units": 1
  }
}
```

## Check your current usage

Authenticated customers can inspect their current monthly usage with:

```http theme={null}
GET /v1/usage/current
```

The endpoint requires the same server-side API key used by other protected
The Wo endpoints:

```http theme={null}
x-api-key: <your-api-key>
```

Example:

```bash theme={null}
curl \
  --request GET \
  --url <your-api-base-url>/v1/usage/current \
  --header "x-api-key: <your-api-key>"
```

Example response:

```json theme={null}
{
  "period": {
    "startsAt": "2026-08-01T00:00:00.000Z",
    "endsAt": "2026-09-01T00:00:00.000Z"
  },
  "usage": [
    {
      "operation": "evidence_report",
      "used": 120,
      "limit": 500,
      "remaining": 380
    }
  ]
}
```

### Response fields

| Field             | Meaning                                                       |
| ----------------- | ------------------------------------------------------------- |
| `period.startsAt` | Inclusive beginning of the current UTC monthly quota period.  |
| `period.endsAt`   | Exclusive end of the period and beginning of the next period. |
| `operation`       | Usage operation represented by the item.                      |
| `used`            | Units recorded for the operation during the current period.   |
| `limit`           | Monthly limit configured by the customer's active Plan.       |
| `remaining`       | Units still available, never lower than `0`.                  |

Remaining usage is calculated as:

```text theme={null}
max(limit - used, 0)
```

Usage Records are the source of truth for `used`.

The endpoint sums recorded `units` for the authenticated customer, operation,
and current UTC calendar month.

A customer with no usage receives `used: 0`; this is not a `404`.

Reading current usage is free and does not create another Usage Record.

### Current usage access

If current usage is not available for the authenticated customer's active Plan,
the API returns:

```text theme={null}
403 current_usage_access_denied
```

If current usage cannot be read safely because a required service is
temporarily unavailable, the API returns:

```text theme={null}
503 current_usage_unavailable
```

The API never reports fabricated zero usage when the real value cannot be read.

### Customer usage page

The MVP does not provide a dedicated customer usage dashboard.

`GET /v1/usage/current` is the customer-facing MVP surface and can later power
a customer page without changing the usage contract.

## When usage is recorded

The current operation lifecycle is:

```text theme={null}
authenticate
→ validate request
→ apply technical rate limit
→ apply idempotency when requested
→ check quota
→ securely retrieve remote images when present
→ generate report
→ persist report
→ record usage
→ return success
```

Usage is therefore not recorded for failures that occur before usage
recording.

Monthly quota is checked before remote image retrieval. A request rejected by
quota cannot use Operational Evidence as a remote-resource downloader. Remote
image retrieval failures also occur before provider execution and before Usage is
recorded.

Examples include:

* authentication failure;
* invalid HTTP payload;
* invalid application input;
* quota rejection;
* remote evidence image rejection;
* remote evidence image unavailability;
* provider unavailability;
* provider generation failure;
* invalid generated output;
* Evidence Report persistence failure.

## Monthly quota

Quota is evaluated per customer and operation.

The current MVP uses UTC calendar months.

A quota period begins at:

```text theme={null}
00:00:00 UTC on the first day of the month
```

and ends immediately before:

```text theme={null}
00:00:00 UTC on the first day of the next month
```

For example:

```text theme={null}
2026-08-01T00:00:00.000Z
≤ usage timestamp
< 2026-09-01T00:00:00.000Z
```

## Quota decision

For the current create Evidence Report endpoint:

```text theme={null}
requested units = 1
```

The operation is allowed only when enough units remain before the request.

For example, with a monthly limit of `500`:

| Used | Requested | Result  |
| ---: | --------: | ------- |
|    0 |         1 | Allowed |
|  498 |         1 | Allowed |
|  499 |         1 | Allowed |
|  500 |         1 | Blocked |
|  501 |         1 | Blocked |

The final available unit can therefore be consumed.

## Quota exceeded

When the request would exceed the current monthly quota, the API returns:

```http theme={null}
HTTP/1.1 429 Too Many Requests
```

with:

```text theme={null}
quota_exceeded
```

Example:

```json theme={null}
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly operation quota has been exceeded.",
    "requestId": "req_123",
    "details": {
      "operation": "evidence_report",
      "limit": 500,
      "used": 500,
      "remaining": 0,
      "requestedUnits": 1,
      "resetAt": "2026-09-01T00:00:00.000Z"
    }
  }
}
```

## Understanding quota details

| Field            | Meaning                                                |
| ---------------- | ------------------------------------------------------ |
| `operation`      | Usage operation being checked.                         |
| `limit`          | Monthly limit for the operation.                       |
| `used`           | Units already recorded in the current period.          |
| `remaining`      | Units available before the rejected request.           |
| `requestedUnits` | Units required by the current request.                 |
| `resetAt`        | UTC timestamp at which the next monthly period begins. |

`remaining` describes availability before the current request.

It never represents a negative value.

## Customer or Plan access

Quota exhaustion is different from not having access to the billable
operation.

When the authenticated customer does not have a valid active Plan relationship
for the operation, the API returns:

```http theme={null}
HTTP/1.1 403 Forbidden
```

with:

```text theme={null}
quota_access_denied
```

This is not treated as quota exhaustion.

## Quota validation unavailable

Quota checks fail closed.

If The Wo cannot safely determine whether the operation is allowed, report
generation does not start.

The API returns:

```http theme={null}
HTTP/1.1 503 Service Unavailable
```

with:

```text theme={null}
quota_check_unavailable
```

## Payment Required

The current MVP does not use:

```text theme={null}
402 Payment Required
```

for monthly quota exhaustion.

`402` is reserved for a future explicit product decision involving payment or
subscription state.

## Overage billing

Automatic overage billing is not part of the current MVP.

A request that exceeds the available monthly quota is rejected instead of
being automatically billed above the configured limit.

## Concurrent requests

The current MVP calculates quota from recorded usage before executing the
operation.

Multiple concurrent requests can temporarily observe the same final available
unit.

Strict concurrent reservation is not part of the current public MVP.

Customers that require strict high-concurrency quota guarantees should discuss
that requirement before production onboarding.

## Retrying quota errors

A `429 quota_exceeded` request should not be retried repeatedly.

Retry after:

* quota becomes available;
* the next monthly period begins;
* or your Plan changes.

The `resetAt` field identifies the beginning of the next UTC quota period.