Usage

Status: Developer preview — contract-stable per @nexislabs/ai-platform v1; not yet serving public traffic.

GET /v1/usage

​

Authentication

​

What backs it

• Billing runs on a reserve → settle → reconcile pipeline over ai_usage_events, with immutable price versions and margin-floor pricing (minimum_margin_bps, payment_fee_bps).
• Usage is denominated through the existing token → micros → credits pipeline (usage_events).
• Bundled inference is priced against the platform’s credit machinery; BYO inference is charged a platform fee on routed spend instead of a token margin — both are priced through the same telemetry so the readback shape does not depend on funding mode (design spec §3.4).
• Per-run token/tool-call counts are available on the event stream as the usage event (inputTokens, outputTokens, modelCalls, toolCalls). This is not the same object as the tenant-level aggregate this endpoint returns — one is a per-run streamed event, the other is a tenant-scoped readback across runs.

​

Response

Gap. The design spec confirms this endpoint exists and what it is scoped to (“tenant-scoped usage/spend readback”), and lists the billing machinery it is built on, but does not publish a response schema. The @nexislabs/ai-platform package in this corpus exports no type for it. Field names, pagination, and date-range filtering are unspecified. The design spec assigns finalizing this surface to Workstream F4 (developer surface) atop Workstream S1 (metering/billing authority transfer).

​

Example

curl https://api.praxa.io/v1/usage \
  -H "Authorization: Bearer praxa_sk_live_xxxxxxxxxxxxxxxxxxxx"

​

TypeScript

// Response shape is not yet published — treat as opaque until the
// finalized schema ships (see the Gap note above).
async function getUsage(apiKey: string): Promise<unknown> {
  const res = await fetch("https://api.praxa.io/v1/usage", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  if (!res.ok) throw new Error(`usage fetch failed: ${res.status}`);
  return res.json();
}