Usage and limits

For POST /v1/validation, completed work is measured with the vu_v1 Validation Unit meter and capacity is shared at the organization level. Usage remains attributable to the credential that performed it.

Inspect Validation Intelligence usage

Call the typed organization usage endpoint with the same supported credential method as validation:

curl "$IVORLEAF_API_BASE_URL/v1/validation/usage/status" \
  --header "X-API-Key: $IVORLEAF_API_KEY" \
  --header "X-Ivorleaf-Client: api"

GET /v1/validation/usage/status returns:

organization and period identity: organization_id, period_id, period_start, and period_end;
meter and mode: meter_version (vu_v1) and enforcement_mode;
configured capacity components: base_vu, additional_vu, granted_vu, and overage_vu;
totals: available_vu, consumed_vu, nullable remaining_vu, capacity_exhausted, overage_enabled, and overage_consumed_vu;
a credentials map with credential_id, vu_consumed, workload_count, and validation_count attribution.

Treat the period fields as reported state. This contract does not promise a reset schedule, pricing, plan size, billing rate, or overage price.

Organization-backed credentials may also use GET /v1/api/usage/status where applicable. That compatibility endpoint can add current-credential context, including its operational request-rate limit. For canonical VI capacity and consumption, prefer the typed /v1/validation/usage/status response.

Capacity modes

Mode	External behavior
`shadow`	Records consumption without presenting a finite remaining entitlement. `remaining_vu` is `null`, and validation is not rejected based on the observed VU total.
`enforced`	Enforces the configured total capacity. Work that would exceed it returns `429`.
`overage`	Includes explicitly configured overage VUs in total available capacity. Work that would exceed that configured total returns `429`; `overage_consumed_vu` reports consumption above non-overage capacity.

overage names an enforcement mode, not a published price or promise of automatic unlimited usage.

Capacity is not rate limiting

A 429 can mean either request-rate exhaustion or enforced organization VU-capacity rejection. They are different controls:

request rate limits the number of calls over an operational interval;
VU capacity limits the completed canonical relationship evaluations available to the organization.

Inspect the response detail and current usage state before deciding whether to retry. Respect Retry-After when supplied. Do not assume every 429 will clear on the same schedule.

What consumes VUs

For the complete-matrix validation primitive, VUs equal information units multiplied by independent evidence items. In-progress work, GET polling, duplicate evidence, duplicate task delivery, rejected idempotency conflicts, and completed replay add no VUs; failed or incomplete graphs add no VUs. Determination state does not affect the quantity. Read Validation Units for the complete rule.

Advanced workflow compatibility usage

Session and workflow counters on older compatibility surfaces are not the authoritative consumption model for Validation Intelligence. For a legacy-compatible credential, GET /v1/api/usage/status can report org_id, key_id, owner and plan labels, session/workflow counts and limits, request-rate limits, an unlimited marker, and the current window. That response identifies itself as non-authoritative legacy compatibility and does not claim vu_v1.

Technical Sessions remain a separate advanced workflow with route-specific request, monthly session, workflow, and provider limits where applicable. Their counters do not replace the organization VU status for /v1/validation.