Billing reference
Kilimanjaro bills on six peer-equal dimensions. No dimension reduces to another; none is the "primary" axis. The dimension split preserves the cost signal at the surface level — when a customer optimises, the surface tells them which axis is dominant — while the billing pipeline aggregates to dollars at the invoice layer. Every dimension is sparse: it reads $0 until the operation that meters it occurs.
1. The six dimensions
| # | Dimension | Primitive | Surface field | What it meters |
|---|---|---|---|---|
| 1 | Compute — agentic | Governed Operations | meta.cost.governedOps | Governed-action commits: a governed action crossing the Keep enforcement boundary, IRREVERSIBLE_ACTION_GATE redemption, workflow step boundaries |
| 2 | Compute — raw execution | CPU-ms (sandbox) | meta.cost.cpuMs | Raw function execution time |
| 3 | Persistence | Storage GB-month | meta.cost.storageGbMonth (per-call delta) | Database row writes, file uploads, vector-index growth |
| 4 | Data movement | Egress GB | meta.cost.egress.gb + meta.cost.egress.zone | Subscription deliveries, file downloads, API response payloads, function output streams, cross-region replication |
| 5 | Access frequency | API calls | meta.cost.apiCalls | REST / RPC requests not metered as a governed operation or vault op |
| 6 | Vault operations | Kibo ops | meta.cost.vaultOps.<op> | Customer-invoked cryptography: encrypt / decrypt / sign / verify / rotate / fetch (§4) |
Compute is two peer dimensions, not one: a governed operation is a decision commit; a CPU-ms unit is raw work performed. They carry different optimisation levers, so the cost surface keeps them distinct. A single function invocation may carry both — a sandbox function whose work crosses the Keep enforcement boundary commits a governed operation and also accumulates CPU-ms for the execution.
Metered is not the same as billed
All six dimensions are metered — every response carries what it did on meta.cost. Four of them are priced: persistence, data-movement (egress), vault operations, and sandbox compute (CPU-ms, drawn from the pack allowance, then Headroom). Two carry no per-unit price at all — governed operations and API calls. Their presence in meta.cost is evidence of instrumentation, never evidence of a rate.
Governed operations price as capacity, not as events. Governance throughput runs inside a project's reserved GOPS lane (governed-operations-per-second, metered as peak sustained load over a rolling five-minute window). Within the lane there is no per-call charge and no overage meter; over-ceiling traffic shapes and queues at the gateway, and additional headroom is a pre-purchased capacity pack. API calls are the catch-all instrumentation surface and never carry a price. Removing the governed-operation per-unit price is a deliberate pricing decision — a reader should not infer a rate from the meter's continued existence.
Baseline encryption is included, never billed. Every project gets always-on platform-managed encryption protecting system and user secrets at rest — the cryptographic substrate the platform itself depends on to function. Platform-internal crypto on platform-held keys does not meter (per ch08 §9.1). The vault-operations dimension (#6) bills only customer-invoked cryptography — your own keys via BYOK/HYOK, or the Vault Secrets API. A project that relies entirely on baseline encryption shows vaultOps: 0 — sparse, not absent, exactly as a project that makes no API calls shows no apiCalls.
2. The meta.cost response contract
2.1 Sparse population
meta.cost is a dimension-keyed object on the standard response envelope. Each dimension key is populated only when the operation incurred cost on that dimension; absent keys mean zero on that dimension. A response that incurred no metered operation at all (e.g., a 304 Not Modified) carries no meta.cost field — the surface is absent rather than zero-populated.
The forward-compatibility rule lets new dimensions land in subsequent API versions on responses where they apply; older clients reading the response see an unknown key they can ignore.
2.2 Per-dimension shape
interface MetaCost {
// Compute
cpuMs?: number; // CPU milliseconds (sandbox)
waypoints?: number; // integer count
embeddingTokens?: number; // integer count
// Persistence
storageGbMonth?: number; // per-call delta, in GB-month
// Data movement
egress?: {
gb: number;
zone: "intra-region" | "intra-zone" | "inter-zone";
};
// Access frequency
apiCalls?: number; // integer count
// Vault operations
vaultOps?: number; // integer count
}
The governed-operation count is not emitted on meta.cost; the per-operation vault breakdown (encrypt, decrypt, sign, verify, rotate, fetch) is likewise not part of the response.
2.3 Worked examples
List endpoint (no compute beyond the gateway):
{
"data": { "items": [...] },
"meta": {
"cursor": { "next": "..." },
"cost": {
"apiCalls": 1,
"egress": { "gb": 0.000142, "zone": "intra-region" }
},
"context": { "requestId": "req_abc" }
}
}
Sandbox function invocation writing a row:
{
"data": { "id": "doc_xyz", "status": "created" },
"meta": {
"cost": {
"apiCalls": 1,
"cpuMs": 73,
"storageGbMonth": 0.0000041,
"egress": { "gb": 0.0000098, "zone": "intra-region" }
},
"context": { "requestId": "req_def" }
}
}
BYOK encrypt operation:
{
"data": { "ciphertext": "..." },
"meta": {
"cost": {
"vaultOps": 1,
"egress": { "gb": 0.0000051, "zone": "intra-region" }
},
"context": { "requestId": "req_ghi" }
}
}
(apiCalls is omitted — the vault-op dimension covers the API-surface cost for vault operations.)
2.4 Cost on the error path
A request that returns a KError does not carry a meta.cost field. Cost-relevant metadata, where applicable, surfaces in KError.context:
| Error code | Context fields |
|---|---|
K9O_TIER_CAP_HIT | tier, dimension, capPeriod, capLimit, capUsed, resetAt, upgradeUrl |
K9O_TIER_RATE_LIMIT_EXCEEDED | windowSeconds, limit, used, retryAfterSeconds |
K9O_STORAGE_QUOTA_EXCEEDED | tier, quotaGb, usedGb |
K9O_EGRESS_QUOTA_EXCEEDED | tier, zone, quotaGb, usedGb |
K9O_VAULT_OP_QUOTA_EXCEEDED | tier, opType, quotaOps, usedOps |
Counting rule. Count on operation initiation when the customer's intent has been recorded in platform state OR when external compute / vendor cost has been incurred; do not count when the operation was rejected synchronously before any state change or vendor call. A 4xx that fails synchronously at the gateway does not consume cost on any dimension. A 5xx after partial work consumes cost on the dimensions where work occurred.
3. Operation semantics drives metering
Metering follows the operation's semantics, not the caller's auth context. Two questions decide the dimension:
- Does the operation commit a policy-gated decision? → governed-operation dimension.
- Does the operation pass through the API surface but commit no policy-gated decision? → access-frequency dimension.
The same operation costs the same whether the caller authenticated as a human user, a service token, an extension plugin token, or the anonymous API key. Auth context determines who is responsible for the cost (visible via meta.context); it does not determine what the cost is.
This forecloses two would-be optimisations:
- "I'll authenticate as a service account to make my decision-committing calls non-governed." — No. The governed operation is the operation, not the auth context.
- "I'll invoke from inside a function so the call isn't a 'real' API call." — No. The function execution still emits its own dimension surfaces (for example
cpuMs) plus any downstream operations the function triggers.
4. Vault operations dimension
Vault operations is dimension #6 (§1). It bills customer-invoked cryptography only — baseline platform encryption of your secrets and data at rest is non-billable infrastructure (ch08 §9.1). The six billable Kibo operations:
| Operation | When it bills |
|---|---|
encrypt | DEK wrap or AEAD-encrypt that produces ciphertext |
decrypt | DEK unwrap or AEAD-decrypt |
sign | Ledger-event sign on the ledger-write path (BYOK / HYOK) |
verify | Signature verification on the BYOK / HYOK decrypt path |
rotate | Key-rotation initiation |
fetch | External KMS / HSM fetch (BYOK / HYOK; triggered by re-wrap and decrypt) |
A single Kibo operation may emit multiple counters. A BYOK encrypt under a freshly-rotated key emits both encrypt: 1 and fetch: 1. A chain-write emits sign: 1. The cost model treats each counter as an independent line item.
Partial-failure semantics. A wrap or AEAD-encrypt failure before producing ciphertext is NOT counted. A sign that succeeded but failed to commit the ledger event is NOT counted. A fetch whose external call was dispatched and returned an error IS counted (vendor-side compute consumed). A rotate that initiated and partway-failed IS counted (one rotation).
Non-billable operations. Read-only vault operations — listing keys, viewing key detail, fetching the audit ledger, verifying the ledger, vault status — do not bill.
5. Compute dimension
5.1 Governed Operation emission
A governed operation is a governed action crossing the Keep enforcement boundary — one meaning, platform-wide. There is no hand-incremented SDK counter; a governed operation emits on:
- A governed action crossing the Keep enforcement boundary — counts 1, metered identically on every verdict (an allowed action and a denied one consume the lane the same way; a deny does not rebate).
IRREVERSIBLE_ACTION_GATEredemption (token accepted, action committed) — counts 1.- Workflow step boundary — counts 1 per step.
Governed operations accrue against the project's reserved GOPS lane and carry no per-unit price (§1) — the count is the governance-throughput signal, and capacity is what the customer purchases.
5.2 CPU-ms
Sandbox work bills in sandbox CPU-ms (CPU milliseconds of active execution): functions, extensions, workflows and Warden. It is metered when the sandbox VM ends, so every entry point is covered. Usage is drawn from the allowance that rides on the capacity pack (100M CPU-ms a month per pack) and then, if Headroom is on, billed per million CPU-ms; otherwise it throttles. Sandbox invocations are counted and reported, never priced per request.
6. Persistence dimension
Persistence aggregates database row writes, file uploads, and vector-index growth into a single storage GB-month dimension. The per-response storageGbMonth field reports the per-call delta; the running monthly total aggregates continuously.
Retention prorates: a row written on day 15 of the month accrues 16 days of storage, not 30. Storage tiered to cold archival accrues at the cold-tier rate from the tiering event onwards.
7. Data movement dimension
Egress is metered in three zones:
| Zone | What it covers |
|---|---|
intra-region | Traffic that stays within the project's pinned region |
intra-zone | Cross-region traffic between regions that share at least one zone (e.g., Lagos to Johannesburg, or Singapore to Sydney) |
inter-zone | Traffic between regions that share no zone (e.g., EU project ↔ US consumer), labelled "Cross-Zone Transfer" on customer-facing billing surfaces |
The three zones have different unit prices reflecting the underlying network cost. The meta.cost.egress.zone value lets cost analysis attribute egress to the correct zone for forecasting.
Subscription deliveries and cross-region replication payloads are metered as egress in the same zone vocabulary.
8. Access frequency dimension
Any 2xx / 3xx / 4xx response that did not surface as a governed operation or vault op increments apiCalls by 1. This is the catch-all dimension for the API surface itself — requests where the metering primitive is "this call happened" rather than payload bytes or decision commits.
9. Tier caps and overage
9.1 Cap states: throttle, Headroom, and hard cap
When a project exhausts its monthly tier allowance on a monthly-capped dimension (governed operations, persistence, egress, vault ops), that dimension sits in one of three cap states. This is the model post-rung-1; it supersedes any earlier "hard on Ascent/Ridge, soft on Summit" framing.
- Throttle — the gateway paces throughput down once the allowance is consumed; operations are not rejected and no overage is billed. This is the default on every paid tier (Ascent / Ridge / Summit / Sovereign Control / Private Perimeter) for every capped dimension. The throttle surfaces in observability alongside an in-Console upgrade nudge — never a surprise bill.
- Soft cap (Headroom) — on the priced dimensions (persistence, egress, vault operations), a tenant can opt into Headroom per dimension: operations succeed and accrue overage at the published rate-card rate above the allowance, optionally ceilinged by a monthly spend cap. Governed operations carry no per-unit price (§1), so they have no Headroom-billing state — over-ceiling governance throughput shapes inside the reserved GOPS lane and added capacity is a pre-purchased pack, never event-level overage. See the billing guide for the mental model.
- Hard cap — operations are rejected. Surface:
K9O_TIER_CAP_HIT(409). This is the Base Camp (Free) default on governed operations and vault ops, with a daily reset — it never bills; the cap exists to prompt an upgrade, not to charge.
A hard-cap rejection carries the cap context for remediation:
{
"code": "K9O_TIER_CAP_HIT",
"message": "Project daily governed-operation cap reached.",
"context": {
"tier": "base-camp",
"dimension": "waypoints",
"capPeriod": "2026-05",
"capLimit": 500,
"capUsed": 500,
"resetAt": "2026-05-15T00:00:00Z",
"upgradeUrl": "https://<orgSlug>.console.k9o.io/billing"
}
}
Paid tiers throttle by default — they do not silently hard-cap or bill on allowance exhaustion. Billing above the allowance happens only on the priced dimensions where the tenant has explicitly enabled Headroom. Governed operations, apiCalls, and MAU never participate in overage billing — they carry no per-unit price at any state (§1, §8, §10).
Headroom is elected per dimension, at the org level (the org is the paying entity), via a dedicated org-plane surface:
GET <orgSlug>.api.k9o.io/billing/headroom
POST <orgSlug>.api.k9o.io/billing/headroom
Each dimension carries { enabled, spendCapCents }: enabled: false (the default) throttles on exhaustion; enabled: true bills elastic above the allowance, optionally ceilinged by a monthly spendCapCents after which the dimension reverts to throttle for the rest of the period. The per-project PATCH <orgSlug>.api.k9o.io/@<projectSlug>/billing/cap-mode surface sets a project's soft / hard / throttle mode. Changing a Headroom election or a cap-mode emits a tier.cap_mode_changed audit event.
9.2 Concurrency caps
The platform enforces per-project concurrency caps at the gateway as abuse-prevention / fair-resource rails — they are not billing primitives. A project hitting its concurrency cap returns K9O_TIER_RATE_LIMIT_EXCEEDED (429); cap-hits do not consume metered cost on the rejected request.
10. Gate (IAK) MAU model
Gate is metered on a separate Monthly-Active-Users (MAU) headline dimension, distinct from the six metered dimensions (§1) — MAU is a Free-tier ceiling, not a per-unit cost axis, and it never appears in the meta.cost block. MAU is the rolling-30-day count of distinct end-user identities (subject.id of form eu_<base62>) that authenticated via Gate flows in the project.
| Tier | MAU cap | Cap behaviour |
|---|---|---|
| Free | 50,000 | Hard cap. The 50,001st distinct signup in the rolling-30-day window fails with K9O_TIER_CAP_HIT (409). |
| Ascent + Ridge + Summit + Sovereign Control + Private Perimeter | Unlimited | No MAU cap. MAU does not participate in overage metering. |
Users are free; you pay for the work they do. Paid-tier MAU is unbounded by design; revenue accrues on the six metered dimensions (§1) generated as end-users interact with the platform. The Free-tier 50K MAU cap is the abuse-vector ceiling.
10.1 Gate SDK surface
The Gate SDK surface is uniformly available on every plan, and to every project: core Gate and the standard auth-feature surface, and the gate.federation.* sub-namespace (SAML configuration, SCIM provisioning, IdP federation primitives). Federation is not gated by plan. What differs between plans is the usage allowance, not the capability.
10.2 Anti-abuse rate limits
In addition to the headline MAU cap, the Free tier carries auxiliary per-action rate limits:
| Capability | Free-tier cap |
|---|---|
| Per-IP signup rate | 100 / minute, 1,000 / hour |
| CAPTCHA progressive challenge | After 10 signups in a 60-second window from the same IP block |
Transactional email sends (gate.email.send) | 100 / day / project |
Transactional SMS sends (gate.sms.send) | 50 / day / project |
OTP request rate (gate.passwordless.requestOtp / requestMagicLink) | 5 / minute / end-user-or-IP |
Rate-limit hits return the standard rate-limit envelope with Retry-After headers.
11. Cost data API
11.1 Per-project cost surface
GET <orgSlug>.api.k9o.io/@<projectSlug>/billing/cost
Returns the running cost surface for the current billing period:
{
"data": {
"projectId": "proj_xyz",
"period": "2026-05",
"tier": "ascent",
"dimensions": {
"waypoints": { "count": 47213, "capLimit": 100000, "capUsed": 47213 },
"storageGbHours": { "current": 0.142, "rateGbMonth": 12.4, "capLimit": 50 },
"egress": {
"intra-region": { "gb": 7.42 },
"intra-zone": { "gb": 0.18 },
"inter-zone": { "gb": 0.0 },
"capLimit": 100, "capUsed": 7.6
},
"apiCalls": { "count": 234120 },
"vaultOps": {
"encrypt": 12450, "decrypt": 12380, "sign": 4720, "verify": 4650,
"rotate": 2, "fetch": 18,
"capLimit": 100000, "capUsed": 34220
}
},
"estimatedTotal": { "currency": "USD", "amount": 0.00 }
}
}
estimatedTotal is the running estimate against the current period's tier rates; the final invoice is computed at period close.
Auth: PROJECT_ADMIN or PROJECT_AUDITOR.
11.2 Per-org aggregation
GET <orgSlug>.api.k9o.io/billing/cost
Aggregates per-project cost surfaces under the org. Returns the running cost across all projects in the org with per-project subtotals and an orgSubtotal.
Auth: ORG_ADMIN or ORG_BILLING_VIEWER.
11.3 Historical cost queries
GET <orgSlug>.api.k9o.io/@<projectSlug>/billing/cost/history?from=<period>&to=<period>
GET <orgSlug>.api.k9o.io/billing/cost/history?from=<period>&to=<period>
<period> is a calendar-month identifier (YYYY-MM). Returns one entry per period in the range. Historical periods are sealed — no running estimate; the entry carries the final invoiced amount. Retention is 7 years (matches the Kibo signed audit-ledger retention; cost data is accounting-grade).