AAU Billing Reference
Agentic Activity Unit Weight Table
| Intent category | Example operations | AAU weight |
|---|---|---|
| Read | read_select | 1x |
| Write | write_insert, write_update, write_delete | 3x |
| Governed | admin, cross-system transactions | 5x |
The weight is resolved from the intent context key that the SCHEMABOUND middleware attaches to every LlmToolCallAuditRecorded event. When no explicit intent is present the weight is heuristically derived from the tool/function name (see aau_weight_from_tool_name in services/backend/src/billing.rs).
AAU Billing Heatmap
Interactive visualization of ORM model × intent governance cost distribution. Cell dimensions scale with cumulative AAU total so operators can immediately spot which models and intents drive the most overhead.
Note: This heatmap loads sample data by default. When a running SCHEMABOUND backend is available, replace SAMPLE_DATA in aau-heatmap.js with a fetch call to /api/billing/usage/heatmap.
Event Schema: usage_events Table
| Column | Type | Notes |
|---|---|---|
id | VARCHAR(36) | UUIDv4 |
org_id | VARCHAR(36) | From request context |
session_id | VARCHAR(255) | Optional — agent session |
tool_name | VARCHAR(255) | Raw gRPC/MCP tool name |
intent | VARCHAR(64) | read_select / write_* / admin |
aau_weight | DOUBLE | 1.0 / 3.0 / 5.0 |
orm_model | VARCHAR(64) | ORM model name, if known |
cost_usd | DOUBLE | Reserved for future pricing; currently 0.0 |
created_at | TIMESTAMP | Server timestamp |
REST API Endpoints
All billing endpoints require the caller to be authorised as billing admin (see Authorization below).
GET /billing/usage
Returns daily AAU totals for the authenticated organisation.
Query parameters
| Parameter | Format | Default |
|---|---|---|
from | YYYY-MM-DD | 1970-01-01 (all-time) |
to | YYYY-MM-DD | 9999-12-31 (all-time) |
Response
{
"data": [
{
"date": "2026-04-30",
"action_count": 42,
"total_aau": 87.0,
"total_cost_usd": 0.0
}
]
}
GET /billing/usage/heatmap
Returns AAU totals grouped by ORM model x intent — the matrix consumed by the D3 heat map on the AAU Dashboard.
Response
{
"data": [
{
"orm_model": "Person",
"intent": "write_insert",
"aau_weight": 3.0,
"total_aau": 9.0,
"action_count": 3
}
]
}
POST /billing/setup-intent
Creates a Stripe SetupIntent so the frontend can securely collect card details. Requires STRIPE_SECRET_KEY in the server environment.
Request body
{ "customer_id": "cus_abc123" }
Response — returns id, client_secret, and customer from Stripe.
GET /billing/payment-methods
Lists saved Stripe payment methods for the authenticated admin session.
DELETE /billing/payment-methods/<pm_id>
Detaches a Stripe payment method by its pm_… identifier.
Authorization
Billing endpoints are protected by the BillingAdmin request guard. A request is accepted when either condition is true:
X-User-Roleheader equalsadmin(case-insensitive), orX-User-Permissionsheader containsmanage:billing(comma-separated list).
Requests that satisfy neither condition receive 403 Forbidden.