Usage metering & budget policies

Usage metering is the measured side of the settled stage — it prices what work consumed, in exact units, for every Worker and surface. It answers two operator questions for every tenant: how much did they consume and should the next unit be allowed. It records tenant-scoped, append-only usage events over a closed metric catalog — routing decisions, connector actions, workflow steps, MCP tool calls, and AI tokens in and out are all metered today — aggregates them into bounded rollups, and enforces per-tenant budget policies that can warn, shadow-deny, or hard-deny. This is the plane you use to cap spend and volume per tenant.

Every read and write is tenant-scoped and gated by the usage authz resource type. In production, authenticate as described in Authentication; the local dev examples below run with auth disabled and pass the tenant explicitly via X-Tenant-ID.

The three planes

• Events — an immutable, append-only record of one metered occurrence.
• Rollups — bounded aggregations of events over a window, carrying summed value, event count, and cost.
• Budget policies — per-tenant caps that match events and stamp an outcome onto each recorded event.

The metric catalog (closed set)

Metering accepts only keys from a fixed catalog. An event or policy referencing any other metric_key is rejected at validation. List the live catalog from GET /api/usage/metrics; each descriptor carries a canonical surface and unit.

The usage event

A UsageEvent is one metered occurrence. It is validated on record and again during preview.

correlation carries decision_id, routable_id, pool_id, recipient_id, workflow_id, workflow_run_id, workflow_step_id, agent_definition_id, agent_session_id, experiment_id, experiment_assignment_id, connector_execution_id, sync_run_id, function_run_id, promotion_candidate_id, mcp_request_id, and trace_id — every one optional, so an event can be traced back to what produced it.

Budget policies

A UsageBudgetPolicy is a per-tenant cap. Its match key is the tuple metric_key + surface + unit + dimensions; a policy matches an event when those coordinates agree and every policy dimension is present with the same value on the event (the event may carry extra dimensions).

Windows are UTC calendar-aligned: hour truncates to the hour, day to the UTC day, week to the Monday-start week, month to the first of the month. The window that a given event falls into is derived from its observed_at.

The three actions

shadow_deny is the safe way to roll out a cap: you see exactly which events would have been blocked without actually blocking anything, then promote the policy to deny once the limit is calibrated.

Enforcement

On every recorded event, the service loads matching policies, sums prior usage over each policy's window, and computes a projection.

For each matching policy: projected = used + value, where used is the sum of prior in-window usage.

When several policies match one event, the most restrictive outcome wins and is stamped onto the event, in precedence order denied > shadow_denied > warned > recorded.

Preview: a read-only admission check

POST /api/usage:preview runs the exact same budget evaluation as recording does, but persists nothing. It returns the projected outcome — allowed, a status, and the per-policy decisions — so a caller can decide whether to proceed before doing metered work.

allowed is false only when the projected status is denied; warned and shadow_denied previews are still allowed.

HTTP API

All endpoints are tenant-scoped and gated by the usage resource type (UsageService). Reads use read, writes use write. Rollup and status pages default to 100 rows and cap at 500.

QueryUsage bounds itself: if to is omitted it defaults to now, and if from is omitted it defaults to 24 hours before to. Both QueryUsage and GetUsageBudgetStatus rollups carry cost_micros, making them the per-tenant usage/cost reporting endpoints.

curl "https://your-host/api/usage/metrics" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID"

# Last 24h of AI cost, with raw events included
curl "https://your-host/api/usage?metric_key=ai.cost.usd&include_events=true" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID"

curl "https://your-host/api/usage:preview" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "metric_key": "connector.actions",
    "surface": "connector_action",
    "value": 1,
    "unit": "call"
  }'

# Hard-cap connector actions at 10,000/day, warn at 80%
curl "https://your-host/api/usage/budget-policies" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "metric_key": "connector.actions",
    "surface": "connector_action",
    "unit": "call",
    "window": "day",
    "limit": 10000,
    "action": "deny",
    "threshold_pct": 0.8
  }'

curl "https://your-host/api/usage/budget-status?metric_key=connector.actions" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID"

The same operations are exposed on the MCP operational surface as usage_metrics_list, usage_query, usage_budget_preview, usage_budget_policy_upsert, usage_budget_policy_delete, usage_budget_policies_list, and usage_budget_status.

Setting a cap

Wiring & availability

How the plane is fed

Metering is not called by hand from most places — surfaces emit into it.

Routing

The routing finalizer records routing.decisions for every committed decision via its usage recorder, attaching pool_id, recipient_id, route_outcome, and strategy dimensions plus decision/trace correlation. Dry-run decisions are skipped. See the Routing pipeline.

Connector execution

Connector execution admission calls PreviewUsageImpact as a fact check before running an action, sync, or proxy request. If the projected outcome is a denial, admission is blocked by budget (connector execution blocked by budget). The metered amount per execution is the request's cost_units (default 1). This is where usage budgets meet connector cost accounting — see the Sync engine.

AI inference

The AI inference proxy bridges measured usage into this durable plane. Completed responses emit request, input-token, output-token, and cost events. Every provider attempt emits latency; failed attempts also emit a request and an error event. This preserves retry and failover visibility instead of collapsing a multi-provider request into one opaque total.

AI events carry ai_provider, model, and outcome dimensions. Callers can also supply bounded attribution for agent_definition_id, agent_session_id, workflow_run_id, workflow_step_id, experiment_id, and experiment_assignment_id. Ductor copies those values into both safe dimensions and the typed correlation object, so one cost or latency spike can be traced to the agent, workflow step, and experiment exposure that produced it. Each value is limited to 256 bytes and cannot contain control delimiters.

Cost-bearing events include amount_micros, currency: "USD", the source ductor_static_model_cost_table, and a pricing-table version. Treat this as a versioned Ductor estimate for attribution and budgets, not as a provider invoice. The provenance fields let you recompute or explain historical totals after pricing data changes.

In-process vs. durable budgets

The AI inference proxy also carries its own, separate cost guards — do not confuse them with budget policies.

The "monthly" in-process guard is process-lifetime cumulative spend, not a calendar month. For durable, tenant-scoped, calendar-windowed month caps, use a UsageBudgetPolicy with window: "month". For the in-process guards, see the Inference proxy.

Cost reporting to invoicing

QueryUsage and GetUsageBudgetStatus rollups carry cost_micros, so they are the per-tenant usage and cost reporting endpoints. Accrued billable usage — usd-unit cost rows — can be swept into invoices by the usage-invoicing worker, which is experimental and opt-in (gated off by default). For that pipeline, see the Invoicing integration.

Related