AI credits

AI structured extraction and platform-gateway AI chat are billed against a prepaid, per-(org, app, optional-tenant) micro-USD balance -- a real depleting balance, not a flat per-call charge, because that mirrors how every supported AI vendor actually bills (input tokens, output tokens, and, for providers that support it, cached/discounted input tokens, each priced differently).

Pricing model: cost-plus-markup

Every debit is computed in two steps, in TenancyPlatform.Infrastructure.AI.Providers.AiCreditPricing:

1. Raw vendor cost -- token counts times the vendor's own published per-token rate (stored as nano-USD/token for precision; see that file's rate table for the current per-model prices for Anthropic, OpenAI, Google Gemini, xAI Grok, and DeepInfra).
2. Markup -- a configurable multiplier (AiCreditPricingOptions) applied on top, floored at 1.0x so a misconfigured value can never sell AI credits below vendor cost. Every real arithmetic step in the pricing code rounds up (never down) at each stage, so rounding can never erode the platform's margin.

An unrecognized/new model name is priced at the most expensive known tier (a deliberate over-charge, not an under-charge) rather than silently under-billing. Every real call also debits at least AiCreditPricing.MinimumChargeMicroUsd (1 micro-USD), even for a nominally free-tier model, so a high-volume caller against a "free" model still produces a real ledger signal.

Reserve-then-settle, not charge-after-the-fact: before dispatching a call, the platform reserves a worst-case upper-bound cost (full requested max-output-token budget, no cache discount assumed) against your balance. Once the vendor's real token counts come back, it settles to the true cost and refunds the difference -- so a generous reservation costs you nothing but a temporarily lower visible balance during the in-flight call, and the platform's downside is bounded even if a rate is stale.

Checking and topping up a balance

Both endpoints are on the runtime surface (/api/v1/runtime/applications/{applicationId}), authenticated with your organization API key:

GET /api/v1/runtime/applications/{applicationId}/ai/credits/balance?tenantId={optional}
X-TenancyEngine-Api-Key: te_...

Requires the ai.credits.read scope. Response:

{
  "organizationId": "...",
  "applicationId": "...",
  "tenantId": null,
  "balanceMicroUsd": 4820000,
  "balanceUsd": 4.82,
  "lifetimeGrantedMicroUsd": 10000000,
  "lifetimeSpentMicroUsd": 5180000,
  "updatedAtUtc": "2026-08-26T12:00:00Z"
}

No account provisioned yet (nothing granted or spent) returns the same shape with all balances at zero rather than a 404 -- so a balance display never needs a separate "does an account exist" branch.

POST /api/v1/runtime/applications/{applicationId}/ai/credits/grant
X-TenancyEngine-Api-Key: te_...
Content-Type: application/json

{ "amountMicroUsd": 5000000, "tenantId": null, "externalReference": "purchase-abc123" }

Requires the ai.credits.grant scope, deliberately not folded into any composite scope (including mcp.full) because it moves a real money-equivalent balance -- mint it explicitly. externalReference is the idempotency key a retried purchase webhook needs; a single grant call is capped at $100,000 as a defensive bound against a unit-confusion bug (e.g. sending whole USD instead of micro-USD), not a real business limit.

Spending credits: AI extraction

POST /api/v1/runtime/applications/{applicationId}/ai/extract (requires the ai.extract scope, also deliberately excluded from every composite scope) is the org-API-key-authenticated half of the same structured-extraction feature documented for the Console-session-authenticated path in dev-docs/LOCAL-DEV.md's "AI structured extraction" section in the tenancy-platform repo -- same entitlement gate, same monthly-quota ledger, same schema-forced tool-calling provider path, just reachable from a server-to-server integration instead of a signed-in Console operator. It returns 503 ai_not_configured (no charge) if the environment has no AI provider key configured, and 402 ai_extraction_not_included if your plan doesn't include AI extraction.

Related

• SDK reference -- extractAi/getAiCreditsBalance/grantAiCredits on every SDK
• Platform caching -- the platform's other pay-as-you-go, cost-plus-markup add-on
• API keys -- scopes and key creation