Usage & Cost

Cost on APEX is first-class, not a monthly surprise: every billable call is metered per tenant, priced in South African Rand (ZAR), returned in the response where applicable, and recorded centrally where you can reconcile it. This chapter covers the discipline that makes that useful.

Cost in the response

Products that consume model or compute capacity report the cost of that call in the response:

Product	Where
Zenith	`cost.total_zar` on query/search responses, with a per-component breakdown
Vector	`cost_zar` on verification, risk-scoring, and batch results (`total_cost_zar` on batches)
Forge agent execution	`usage` (input/output/thinking/cache token counts) plus `apex_costs[]` — per downstream APEX call: service, operation, `cost_zar`, duration
Forge LLM gateway (Planned)	`cost_zar` per dispatch; streaming responses end with a terminal `apex_usage` event carrying token counts and cost

Surface these numbers in your own ledger as calls complete — do not wait for the invoice to learn what a feature costs.

Correlation discipline

The join key across your logs, APEX responses, and the platform's usage records is the X-Correlation-ID header:

Generate one identifier per business transaction in your domain — e.g. yourapp:proposal:1042:verify — not per HTTP call.
Send it on every APEX call that transaction makes, across products.
Store it with your own record of the transaction.

If you omit it, the platform generates one per call — the calls are still metered, but you lose the ability to group them into anything meaningful.

Reconciliation

Usage records are queryable in the Forge portal under Billing & Usage (see openapi/forge-portal.yaml):

Transactions — GET /api/tenants/{id}/billing/transactions with periodStart/periodEnd, productId, billable, and cursor paging; each record carries the correlation identifier, product, operation, and cost.
Single transaction — GET …/billing/transactions/{correlationId} returns the full breakdown for one correlated transaction, including per-model token counts and ZAR totals.
Summaries — spend, cost series, and usage summaries for dashboards; invoices and the tenant rate card for commercial reconciliation.

Billing reads are portal-session authenticated in the current release. Programmatic usage export for server-to-server reconciliation is on the platform roadmap — speak to your platform contact if you need it sooner.

Budgets and alerts

Tenant administrators can set a monthly budget and alert thresholds in the portal, and read current standing via the budget-status endpoint. Alerts notify — they do not silently cut traffic. If you need hard spend caps, agree the behaviour with your platform operator.

Entitlements shape cost

Your tier determines which operations you can call at all (e.g. Prism output formats, Vector investigation depth, Echo tool quotas) and at what volume. Exceeding an entitlement is a 403/429, not a bigger bill — see Tenancy & Onboarding. Tier changes are commercial conversations, not API calls.

Practical checklist

[ ] Correlation identifier middleware on your APEX client — every outbound call carries one.
[ ] Log {correlation_id, product, operation, cost_zar} client-side as responses arrive.
[ ] A periodic job reconciles your client-side ledger against GET …/billing/transactions for the period.
[ ] Budget + alert thresholds configured before production traffic.
[ ] Cost anomaly alerting on your side (a runaway retry loop shows up in ZAR before it shows up in errors).