Usage & metering

DeveloperUpdated 9 July 2026

Overview

Aimable records usage for every model call — input, output, and reasoning tokens, cost, latency, and the model used — attributed to the tenant, space, and principal that made the call. Because usage is attributed per space, you get per-space metering for billing and reporting, broken down however you have mapped your spaces.

Reading metrics

Usage is exposed through the observability endpoints. They return aggregated metrics for a time window.

Per space:

bash

curl "$BASE/v1/spaces/$SPACE_ID/observability/metrics?from_timestamp=2026-01-01T00:00:00Z&to_timestamp=2026-02-01T00:00:00Z" \
  -H "X-API-Key: $ADMIN"

Returns total cost, usage broken down by model, latency percentiles (p50/p95), error rate, and trace count for the space.

Tenant-wide (all spaces):

bash

curl "$BASE/v1/admin/observability/metrics?from_timestamp=2026-01-01T00:00:00Z&to_timestamp=2026-02-01T00:00:00Z" \
  -H "X-API-Key: $ADMIN"

Returns per-space metrics plus tenant-level totals — a convenient basis for a billing run across all your spaces.

For request-level detail, fetch a single trace via GET /v1/spaces/{space_id}/observability/traces/{trace_id}, using the X-Request-Id/X-Trace-Id from the original call.

Billing usage export

For billing reconciliation there is a dedicated export that returns a flat per-space × per-model view over a time window:

bash

curl "$BASE/v1/admin/billing/usage-export?from_timestamp=2026-06-01T00:00:00Z&to_timestamp=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Each row carries space_id/space_name, model_id/model_name, token_count_total, cost_usd and trace_count; the envelope adds total_cost_usd and — when multiple tenants are exported — tenant_id and tenant_name per row.

Three things to know:

Two credential modes. A normal principal token (requires the observability:metrics:tenant:read permission) exports your own tenant; platform operators additionally hold a deployment-level export token that can span tenants and pass ?tenant_id= — every use of it is logged.
The window is capped at 92 days — longer ranges return 400. Export month by month for historic backfills.
Check partial. If one or more spaces failed to aggregate, the response sets "partial": true and lists failed_space_ids. Treat those totals as incomplete and re-run before invoicing.

How metering is wired

Usage metrics are backed by your tenant's observability project. To read them, observability must be configured for your tenant. If the metrics endpoints return empty results, confirm that configuration is in place. See Observability.

There is no separate billing API: metering is these usage and cost metrics, which you aggregate per space for your own invoicing.

Limits today

A per-principal rate limit (30 requests/minute) applies to the governed /responses endpoint and returns 429 with Retry-After.
The /responses endpoint supports an optional per-call cost cap (cost_cap_usd).
Hard per-space or per-tenant spend/token quotas are not yet enforced. Track spend via the metrics above and set your own thresholds for now.

Next steps

Provisioning — set up the spaces these metrics report on.
Evaluation — what to validate during an evaluation.