Usage

Status: Available in the production partner preview at https://api.praxa.io/v1/usage for tenant API keys with usage:read.

The SDK contract is tenant scoped:

GET /v1/usage?from=2026-07-01T00:00:00.000Z&to=2026-08-01T00:00:00.000Z&group_by=day
Authorization: Bearer praxa_sk_<64 lowercase hex characters>

Query	Required	Notes
`from`	Yes	RFC 3339 timestamp.
`to`	Yes	RFC 3339 timestamp after `from`; maximum range is 366 days in the management implementation.
`group_by`	No	`hour`, `day`, or `month`; defaults to `day`. The SDK input property is `groupBy`.
`api_key_id`	No	Limits readback to one key owned by the tenant. The SDK input property is `apiKeyId`.

The authenticated developer portal uses the corresponding signed-in route, /api/platform/usage, with workspace=personal and the same snake-case query names. Both routes read the same tenant-scoped evidence projection. The public route accepts the SDK’s groupBy and apiKeyId input properties by encoding them as group_by and api_key_id in the request URL.

Response

{
  "apiVersion": "v1",
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "totals": {
    "requests": 12,
    "runs": 12,
    "inputTokens": 42000,
    "outputTokens": 8100,
    "modelCalls": 24,
    "toolCalls": 0,
    "billableAmountMicros": 153300000
  },
  "series": []
}

Every series item has bucketStart, bucketEnd, and the same usage object. When key-attributed rows exist, byApiKey items have apiKeyId, key name, and the same usage object. The property is omitted when no rows exist.

Evidence boundary

Readback includes only tasks whose immutable api_tenant_id matches the requested tenant and whose owner matches that tenant. Ordinary chat tasks, cross-tenant tasks, and tasks without public-API origin evidence are excluded.

token and model-call counts come only from completed provider-call rows;
billable amount comes from canonical actual_retail_microusd settlement;
API-key attribution requires immutable task_runs.api_key_id;
toolCalls remains zero until a trustworthy per-task public tool-call source exists.

This endpoint reports billing evidence. It does not replace reservation, settlement, reconciliation, entitlement, or invoice authority, and it never exposes provider cost or margin.

TypeScript

const usage = await client.getUsage({
  from: "2026-07-01T00:00:00.000Z",
  to: "2026-08-01T00:00:00.000Z",
  groupBy: "day",
});

console.log(usage.totals.billableAmountMicros, usage.currency);

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Response

Evidence boundary

TypeScript

​Response

​Evidence boundary

​TypeScript

Response

Evidence boundary

TypeScript