> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> GET /v1/usage

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

```
GET /v1/usage
```

Tenant-scoped usage/spend readback (design spec §3.1's exact wording). No
query parameters, request fields, or response fields are specified at the
field level by either source in scope for this reference — see the note
below.

## Authentication

Bearer API key, prefix `praxa_sk_`. The readback is scoped to the calling
key's tenant; there is no tenant-id parameter.

## 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](/fabric/api/execute) is priced against the platform's credit
  machinery; [BYO inference](/fabric/api/webhooks) 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](/fabric/api/events#telemetry) (`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

```bash theme={null}
curl https://api.praxa.io/v1/usage \
  -H "Authorization: Bearer praxa_sk_live_xxxxxxxxxxxxxxxxxxxx"
```

## TypeScript

```ts theme={null}
// 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();
}
```