Usage, quota and billing

Where quota sits

These are different questions from whether an action is permitted, so quota is checked at stage S3:rate-quota of the lifecycle, before the arguments are looked at and well before the policy engine. A permitted call can be refused for want of quota, and a call policy would deny can be refused for quota first.

How it works

1. Every governed call consumes one unit from two buckets at once, the project's and the organization's, before it executes.
2. Both buckets are counted over a sliding window: calls in the last sixty seconds, not since a clock minute began, so a burst gets no free reset.
3. A full bucket refuses the call with 429 and a Retry-After header.
4. Credits are separate. They are never read on the governed call path.

A ceiling of 0 means unlimited, and that bucket is not checked at all.

How usage is counted

• One governed tool call is one request, whatever the work. A query-context returning one node and one returning fifty count the same. Nothing measures tokens, result size, graph writes or compute.
• Both buckets are consumed, or neither. A call refused by the project ceiling spends no organization unit, so one runaway project cannot drain the organization through its refusals.
• A refused call consumes nothing, so retrying into a 429 in a tight loop does not push recovery away. Only a call that passes S3 counts, so a policy denial at S5 or an approval parked at S6 has already spent one.
• A resumed call consumes another unit, since redemption of a resume token happens after S3. Budget gated operations at twice the request count.
• The surface makes no difference. The Wexa MCP server, REST and both SDKs hit the same two buckets.

The gateway records the count and ceiling a call saw onto its trace, so a run slowed by a nearly-full bucket can be seen to have been.

Check your consumption

Console: Settings, then Usage & Cost (/settings/usage). API: the documentation tool's governance topic returns it, to any caller.

curl -X POST https://fabric.wexa.ai/v1/docs \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"governance"}'

const docs = await fabric.docs({ topic: 'governance' })
console.log(docs.quota)

docs = fabric.docs(topic="governance")
print(docs["quota"])

"quota": { "project_window_used": 114, "project_window_max": 120,
           "org_window_used": 114,     "org_window_max": 600 }

When a ceiling is reached

The call is refused with 429. This is a real refusal, captured on the 121st call inside the window:

{
  "content": [
    { "type": "text",
      "text": "error (S3:rate-quota): quota exceeded for project proj_d18 (retry after 24s)" }
  ],
  "isError": true
}

HTTP/1.1 429 Too Many Requests
Retry-After: 24

{"error":"S3:rate-quota",
 "error_description":"quota exceeded for project proj_d18 (retry after 24s)",
 "lifecycle_id":"qlc_000126"}

import { QuotaExceeded, isRetryable } from '@wexa-fabric/sdk'

try {
  await fabric.saveContext({ nodes })
} catch (e) {
  if (e instanceof QuotaExceeded) {
    // isRetryable(e) is true; the SDK honours Retry-After when retry is enabled.
  }
}

from wexa import QuotaExceeded

try:
    fabric.save_context(nodes=nodes)
except QuotaExceeded as e:
    print(e.retry_after)

• The message names the bucket. for project … is one noisy project, for organization … is every project at once.
• Retry-After is computed, not constant. It is the time until the oldest call in the window ages out, the earliest moment the call could succeed. Sampled over one recovery it read 24, then 6, then the call succeeded. Both SDKs treat quota exhaustion as retryable and wait that long; it is one of only two error classes either retries, the other being an upstream failure, and the only one either retries a resumed call through. See errors and retries.
• The refusal is audited as a rejection at stage S3:rate-quota, so "we were throttled at 14:05" is checkable for as long as the trail survives. See audit and compliance.

Limits and behavior

When the agent limit is full, both calls fail with a ValidationError (400) carrying Customer has exceeded number of coworkers. That is a limit, not a bad request, so retrying will not help; ask whoever manages your plan for a higher one.

It is checked when the agent or process flow is created, not at S3:rate-quota, and uses no request quota.

To plan against the ceilings:

• Batch where the tool lets you. A single save-context carrying fifty nodes costs one unit; fifty calls of one node cost fifty.
• Expect an agent to spend more than its useful calls. A policy denial or approval gate has still consumed quota and the resume consumes more.
• Watch the organization ceiling, not only the project one.

Where credits live

Credits are a real part of the Wexa product: a balance is held against a workspace, top-ups are purchased, and consumption is reported in the product's billing and utilization views. They are held and spent through the /credits/* endpoints rather than any of the four surfaces.

No lifecycle stage consults a balance, no tool call deducts from one and no Wexa surface returns one or refuses a call for want of credits.

• The balance answers "what did we buy", the quota counters "how hard are we calling". Neither answers the other.
• A drained balance does not stop governed calls, and exhausted quota does not preserve credit. Do not use one as a safety net for the other.
• The balance is shown at Settings, then Billing (/settings/billing), an owner-tier capability. See members and roles.

Reconcile a bill

Reconciliation is possible but partial. Wexa can corroborate three things:

1. That calls happened, and which. Every governed call writes an audit event naming the tool, actor, project and lifecycle identifier, so counting *.executed events per project is a defensible usage figure.
2. That refusals happened. Rejections at S3:rate-quota are recorded separately, so throttled traffic is not counted as served.
3. Which project each call belonged to, for reading though not as a cryptographic assurance: the project identifier is outside the audit hash chain.

It cannot supply three others:

1. Anything predating the last restart. The audit trail is not durable, so unless you archive it, last month's usage record does not exist. This is the largest obstacle.
2. A per-call cost. No cost, token count or credit amount is attached to any event on the governed path.
3. A tie between a call and a credit movement. No identifier is shared between the audit trail and the credits ledger.

A workable routine:

1. Archive GET /v1/audit continuously into your own storage, following the archiving routine in audit and compliance.
2. Count *.executed events per project per period as your usage denominator.
3. Take the credit ledger from the main application as your cost numerator.
4. Reconcile at project level, not call level, and say so. The per-call join does not exist.

Related

• Credential management: the per-key ceiling and who should hold a key.
• Lifecycle and audit: where S3 sits among the stages, in order, and why that decides what is safe to retry.
• Observability: reading the usage a call saw and finding the run that exhausted a bucket.