Usage and quotas

Operational Evidence tracks usage by customer and operation. The current operation identifier is:

evidence_report

Usage unit

Each successfully completed Evidence Report consumes:

1 evidence_report unit

A successful response includes the usage associated with that report:

{
  "usage": {
    "operation": "evidence_report",
    "units": 1
  }
}

Check your current usage

Authenticated customers can inspect their current monthly usage with:

GET /v1/usage/current

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

x-api-key: <your-api-key>

Example:

curl \
  --request GET \
  --url <your-api-base-url>/v1/usage/current \
  --header "x-api-key: <your-api-key>"

Example response:

{
  "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:

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:

403 current_usage_access_denied

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

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:

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:

00:00:00 UTC on the first day of the month

and ends immediately before:

00:00:00 UTC on the first day of the next month

For example:

2026-08-01T00:00:00.000Z
≤ usage timestamp
< 2026-09-01T00:00:00.000Z

Quota decision

For the current create Evidence Report endpoint:

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/1.1 429 Too Many Requests

with:

quota_exceeded

Example:

{
  "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/1.1 403 Forbidden

with:

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/1.1 503 Service Unavailable

with:

quota_check_unavailable

Payment Required

The current MVP does not use:

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.

Overview

Getting started

Product guides

Examples

Usage and quotas

Usage and quotas

Usage unit

Check your current usage

Response fields

Current usage access

Customer usage page

When usage is recorded

Monthly quota

Quota decision

Quota exceeded

Understanding quota details

Customer or Plan access

Quota validation unavailable

Payment Required

Overage billing

Concurrent requests

Retrying quota errors

​Usage and quotas

​Usage unit

​Check your current usage

​Response fields

​Current usage access

​Customer usage page

​When usage is recorded

​Monthly quota

​Quota decision

​Quota exceeded

​Understanding quota details

​Customer or Plan access

​Quota validation unavailable

​Payment Required

​Overage billing

​Concurrent requests

​Retrying quota errors

Usage and quotas

Usage unit

Check your current usage

Response fields

Current usage access

Customer usage page

When usage is recorded

Monthly quota

Quota decision

Quota exceeded

Understanding quota details

Customer or Plan access

Quota validation unavailable

Payment Required

Overage billing

Concurrent requests

Retrying quota errors