Usage

GET /v1/usage returns a UsageSummary — aggregated consumption for your org over a time range. Granular per-event data is internal; this endpoint gives you the roll-up that powers dashboards and billing reconciliation.

Query a period

Pass either a named period or an explicit period_start / period_end range (ISO-8601 timestamps).

TypeScript

const summary = await client.usage.summary({ period: "current_month" });
console.log(summary.total_billable_seconds, summary.sessions_completed);

// Or an explicit range:
const range = await client.usage.summary({
  periodStart: "2026-05-01T00:00:00Z",
  periodEnd: "2026-06-01T00:00:00Z",
});

curl

# Named period
curl "https://api.protoface.com/v1/usage?period=current_month" \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

# Explicit range
curl "https://api.protoface.com/v1/usage?period_start=2026-05-01T00:00:00Z&period_end=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

period accepts current_month and previous_month.

The summary shape

| Field | Type | Notes | | ------------------------- | ----------------------------------- | -------------------------------------- | | period_start | timestamp | | | period_end | timestamp | | | sessions_started | int | | | sessions_completed | int | | | sessions_failed | int | | | total_billable_seconds | int | | | total_frames | int | | | by_transport | { [transport_type]: UsageBucket } | Keys: livekit, fake, … | | by_quality | { [quality_tier]: UsageBucket } | Keys: mock, lite, standard, pro |

Each UsageBucket is:

{
  "sessions": 12,
  "billable_seconds": 7320,
  "frames": 183000
}

Note

Usage is eventually consistent. The summary reflects completed worker reporting and may lag live sessions by a heartbeat interval. For live, per-second figures on a single session, read the usage block on the session object.

Next

Limits & quotas The caps and rate limits your usage is bound by.

Sessions Where billable usage comes from.