Read tenant-scoped usage evidence

curl --request GET \
  --url https://api.praxa.io/v1/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.praxa.io/v1/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "apiVersion": "v1",
  "from": "2026-08-13T12:00:00.000Z",
  "to": "2026-08-13T12:00:00.000Z",
  "currency": "currency-demo-0001",
  "totals": {
    "requests": 0,
    "runs": 0,
    "inputTokens": 0,
    "outputTokens": 0,
    "modelCalls": 0,
    "toolCalls": 0,
    "billableAmountMicros": 0
  },
  "series": [
    {
      "bucketStart": "2026-08-13T12:00:00.000Z",
      "bucketEnd": "2026-08-13T12:00:00.000Z",
      "usage": {
        "requests": 0,
        "runs": 0,
        "inputTokens": 0,
        "outputTokens": 0,
        "modelCalls": 0,
        "toolCalls": 0,
        "billableAmountMicros": 0
      }
    }
  ]
}

GET

usage

Read tenant-scoped usage evidence

curl --request GET \
  --url https://api.praxa.io/v1/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.praxa.io/v1/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "apiVersion": "v1",
  "from": "2026-08-13T12:00:00.000Z",
  "to": "2026-08-13T12:00:00.000Z",
  "currency": "currency-demo-0001",
  "totals": {
    "requests": 0,
    "runs": 0,
    "inputTokens": 0,
    "outputTokens": 0,
    "modelCalls": 0,
    "toolCalls": 0,
    "billableAmountMicros": 0
  },
  "series": [
    {
      "bucketStart": "2026-08-13T12:00:00.000Z",
      "bucketEnd": "2026-08-13T12:00:00.000Z",
      "usage": {
        "requests": 0,
        "runs": 0,
        "inputTokens": 0,
        "outputTokens": 0,
        "modelCalls": 0,
        "toolCalls": 0,
        "billableAmountMicros": 0
      }
    }
  ]
}

Read tenant-scoped Praxa usage totals and UTC time buckets for a bounded reporting range and optional API key filter.

Availability: Production partner preview. Required scope: usage:read.

Authenticate safely

Create a disposable personal workspace API key with exactly usage:read. Send it as Authorization: Bearer $PRAXA_API_KEY. A Gateway OAuth token, Supabase JWT, provider credential, or organization memory key is not interchangeable with this key. The hosted playground sends the credential from your browser session to the documented API through the configured playground proxy. Use test data, never share the key, and revoke it when the check ends.

Request fields

string

required

Inclusive RFC 3339 range start.

string

required

Exclusive RFC 3339 range end. It must be after from; the management implementation accepts a maximum range of 366 days.

hour | day | month

group_by query parameter.

string

Limit readback to one API key owned by the tenant.

Runnable request examples

curl --fail-with-body -X GET 'https://api.praxa.io/v1/usage?from=2026-08-01T00%3A00%3A00.000Z&to=2026-09-01T00%3A00%3A00.000Z' \
  -H "Authorization: Bearer $PRAXA_API_KEY"

const response = await fetch("https://api.praxa.io/v1/usage?from=2026-08-01T00%3A00%3A00.000Z&to=2026-09-01T00%3A00%3A00.000Z", {
  "method": "GET",
  "headers": {
    "Authorization": `Bearer ${process.env.PRAXA_API_KEY}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(`${response.status}: ${text}`);
console.log(text ? JSON.parse(text) : { status: response.status });

import json
import os
from urllib import error, request

req = request.Request(
    "https://api.praxa.io/v1/usage?from=2026-08-01T00%3A00%3A00.000Z&to=2026-09-01T00%3A00%3A00.000Z",
    method="GET",
    headers={
      "Authorization": f"Bearer {os.environ['PRAXA_API_KEY']}"
    },
)
try:
    with request.urlopen(req, timeout=30) as response:
        text = response.read().decode()
        print(json.loads(text) if text else {"status": response.status})
except error.HTTPError as exc:
    raise RuntimeError(f"{exc.code}: {exc.read().decode()}") from exc

What success means

A 200 response contains evidence-bounded usage for the authenticated tenant and requested range.

Successful response

200 — Evidence-bounded usage totals and time buckets.

required

apiVersion response field.

string

required

from response field.

string

required

to response field.

string

required

currency response field.

object

required

totals response field.

array<object>

required

series response field.

array<object>

byApiKey response field.

{
  "apiVersion": "v1",
  "from": "2026-08-13T12:00:00.000Z",
  "to": "2026-08-13T12:00:00.000Z",
  "currency": "currency-demo-0001",
  "totals": {
    "requests": 0,
    "runs": 0,
    "inputTokens": 0,
    "outputTokens": 0,
    "modelCalls": 0,
    "toolCalls": 0,
    "billableAmountMicros": 0
  },
  "series": [
    {
      "bucketStart": "2026-08-13T12:00:00.000Z",
      "bucketEnd": "2026-08-13T12:00:00.000Z",
      "usage": {
        "requests": 0,
        "runs": 0,
        "inputTokens": 0,
        "outputTokens": 0,
        "modelCalls": 0,
        "toolCalls": 0,
        "billableAmountMicros": 0
      }
    }
  ]
}

Handle failures

Response	Meaning	Safe action
`400 invalid_request`	The method, path, headers, query, or body failed strict validation.	Correct the request; do not retry unchanged input.
`401 authentication_failed`	The bearer key is missing, malformed, expired, or revoked.	Stop and replace the key through the authenticated console.
`403 authorization_failed`	The authenticated key lacks scope or tenant authority.	Request only the missing least-privilege scope; never substitute another tenant ID.
`429 rate_limited`	The principal exceeded a bounded rate.	Honor `retryAfterMs` or `Retry-After`, add jitter, and cap attempts.
retryable `5xx`	The server could not confirm a final response.	Reconcile reads or replay the exact keyed mutation before creating new work.

Example problem

{
  "type": "https://docs.praxa.io/problems/authorization-failed",
  "title": "Authorization failed",
  "status": 403,
  "code": "authorization_failed",
  "detail": "The API key does not grant the required scope.",
  "retryable": false
}

Verify the result

Confirm the response echoes the requested range and grouping.
Check that every bucket is inside the range.
Repeat with an owned API key filter and reject foreign key IDs.

Retry, cleanup, and production use

Treat 401, 403, and 409 as authority or state signals, not generic retry prompts.
For 429 or retryable 5xx responses, follow server retry guidance and keep a bounded attempt budget.
Move the request into a trusted application backend before production; never ship the Praxa key in browser or mobile code.
Revoke the disposable key, disable test webhooks, and erase disposable candidate data after validation.

Continue with API authentication, the failure and retry guide, and the end-to-end coverage matrix.

Last modified on August 14, 2026

Start here

Tasks, runs & usage

Webhooks

Memory candidates

Read tenant-scoped usage evidence

Authenticate safely

Request fields

Runnable request examples

What success means

Successful response

Handle failures

Verify the result

Retry, cleanup, and production use

​Authenticate safely

​Request fields

​Runnable request examples

​What success means

​Successful response

​Handle failures

​Verify the result

​Retry, cleanup, and production use

Authenticate safely

Request fields

Runnable request examples

What success means

Successful response

Handle failures

Verify the result

Retry, cleanup, and production use