> ## Documentation Index > Fetch the complete documentation index at: https://docs.protoface.com/llms.txt > Use this file to discover all available pages before exploring further. # Get usage summary > Return aggregated usage for the calling org over a time range. Pass either `period=current_month` (or `previous_month`) for convenience, **or** an explicit `period_start` / `period_end` pair. The two modes are mutually exclusive. ## OpenAPI ````yaml /openapi.json get /v1/usage openapi: 3.1.0 info: description: > Create realtime avatar sessions. ### Authentication All `/v1/*` endpoints require a live API key: ``` Authorization: Bearer sk_live_... ``` Keys are minted in the dashboard and are scoped to a single environment (staging or prod). ### Idempotency `POST /v1/sessions` may include an `Idempotency-Key` header (any opaque string, <= 255 chars). Retries with the same key inside 24 hours return the first response. The header is optional. ### Errors Every non-2xx response is a JSON body of the form: ```json { "error": { "type": "invalid_request", "code": "transport.unsupported", "message": "transport.type=pipecat is not supported", "param": "transport.type", "request_id": "req_01HXY..." } } ``` Switch on `error.code` (stable lower_snake_case), not `error.message`. ### Pagination List endpoints use cursor pagination: ``` GET /v1/sessions?limit=20&starting_after=sess_01HXY... ``` Response shape: ```json { "object": "list", "data": [...], "has_more": true, "next_cursor": "sess_01HXY..." } ``` summary: Protoface — realtime avatar API for developers. title: Protoface API version: 0.1.0 servers: - description: Production url: https://api.protoface.com security: [] tags: - description: >- Create, retrieve, list, and end realtime avatar sessions. Sessions stream audio in and video out; their lifecycle drives billing. name: sessions - description: >- Avatar definitions. Includes platform stock avatars and customer-uploaded avatars. name: avatars - description: Reusable multimodal inputs and outputs for asynchronous model runs. name: assets - description: Provider-neutral model contracts and modality capabilities. name: models - description: Async model execution with typed multimodal inputs and outputs. name: runs - description: Aggregate usage for billing reconciliation. name: usage - description: >- Public platform metadata — currently just status. Unauthenticated. Internal load-balancer and task health probes exist on this host but are not part of the documented surface. name: platform - description: Direct media sessions for the `pipecat-protoface` avatar video service. name: pipecat - description: Public billing plan metadata for signup and pricing UI. name: billing paths: /v1/usage: get: tags: - usage summary: Get usage summary description: >- Return aggregated usage for the calling org over a time range. Pass either `period=current_month` (or `previous_month`) for convenience, **or** an explicit `period_start` / `period_end` pair. The two modes are mutually exclusive. operationId: get_usage parameters: - description: Convenience period selector; mutually exclusive with explicit range. in: query name: period required: false schema: anyOf: - enum: - current_month - previous_month type: string - type: 'null' description: >- Convenience period selector; mutually exclusive with explicit range. title: Period - description: ISO-8601 UTC. Must be paired with `period_end`. in: query name: period_start required: false schema: anyOf: - format: date-time type: string - type: 'null' description: ISO-8601 UTC. Must be paired with `period_end`. title: Period Start - description: ISO-8601 UTC. Must be paired with `period_start`. in: query name: period_end required: false schema: anyOf: - format: date-time type: string - type: 'null' description: ISO-8601 UTC. Must be paired with `period_start`. title: Period End - description: IANA timezone for daily credit buckets. in: query name: time_zone required: false schema: anyOf: - maxLength: 64 type: string - type: 'null' description: IANA timezone for daily credit buckets. title: Time Zone responses: '200': content: application/json: schema: $ref: '#/components/schemas/UsageSummary' description: Successful Response '400': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Invalid `period` / range. '401': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Missing or invalid API key. '422': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Request body or parameters failed validation. security: - ApiKey: [] components: schemas: UsageSummary: additionalProperties: false description: Aggregated usage; returned by `GET /v1/usage`. examples: - billable_seconds: 14280 by_billing_surface: api: 180 playground: 58 by_model: lightricks/ltx-2.5-fast: 58 minimax/minimax-h3: 180 by_quality: pro: 2280 standard: 12000 by_speech_billing_mode: customer_managed: 180 platform_managed: 58 credits_charged: 238 daily_credits_by_billing_surface: '2026-05-24': api: 180 '2026-05-25': playground: 58 period_end: '2026-05-25T19:00:00Z' period_start: '2026-05-01T00:00:00Z' sessions: 42 properties: billable_seconds: description: Total billable seconds across all sessions in the window. minimum: 0 type: integer by_billing_surface: additionalProperties: type: integer description: '`credits_charged` per billing surface.' type: object by_embed: description: Embed-attributed usage, ordered by credits then time. items: $ref: '#/components/schemas/EmbedUsageSummary' type: array by_model: additionalProperties: type: integer description: >- `credits_charged` per model identifier, across every charge in the window. Charges that are not attributed to a model are omitted, as are charges for internal models that are not offered as customer-facing models, so these values intentionally do not sum to `credits_charged`. Unlike `recent_charges`, this covers the whole window rather than the most recent settled charges. type: object by_operation: additionalProperties: type: integer description: '`credits_charged` per durable billable operation identifier.' type: object by_quality: additionalProperties: type: integer description: >- `billable_seconds` per quality tier. Forward-compatible breakdown — additional `by_*` slices may appear over time. propertyNames: $ref: '#/components/schemas/QualityTier' type: object by_speech_billing_mode: additionalProperties: type: integer description: '`credits_charged` per speech billing mode.' type: object credits_charged: default: 0 description: Total credits charged across all usage events in the window. minimum: 0 type: integer daily_credits_by_billing_surface: additionalProperties: additionalProperties: type: integer type: object description: >- `credits_charged` per requested timezone day and billing surface. Keys use `YYYY-MM-DD`. type: object period_end: description: >- Exclusive end of the aggregated window. Matches the `period_end` query argument. format: date-time type: string period_start: description: >- Inclusive start of the aggregated window. Matches the `period_start` query argument. format: date-time type: string recent_charges: description: >- Most recent settled model and Studio charges in the requested window. items: $ref: '#/components/schemas/UsageChargeSummary' type: array sessions: description: Number of sessions that contributed usage in the window. minimum: 0 type: integer required: - period_start - period_end - billable_seconds - sessions title: UsageSummary type: object ApiErrorEnvelope: additionalProperties: false description: Wire format for every non-2xx public API response. examples: - error: code: transport.unsupported message: transport.type=pipecat is not supported param: transport.type request_id: req_01HXY5K8E7QYG3X8Z6N9R7S0VR type: invalid_request properties: error: $ref: '#/components/schemas/ApiError' required: - error title: ApiErrorEnvelope type: object EmbedUsageSummary: additionalProperties: false description: Usage attributed to one customer-managed avatar embed. properties: avatar_id: type: string avatar_name: anyOf: - type: string - type: 'null' billable_seconds: minimum: 0 type: integer credits_charged: minimum: 0 type: integer embed_id: type: string embed_name: type: string is_active: type: boolean sessions: minimum: 0 type: integer required: - embed_id - embed_name - avatar_id - credits_charged - billable_seconds - sessions - is_active title: EmbedUsageSummary type: object UsageChargeSummary: additionalProperties: false description: One settled model or Studio charge for customer-visible audit history. properties: billing_surface: type: string created_at: format: date-time type: string credits_charged: minimum: 0 type: integer id: type: string model: anyOf: - type: string - type: 'null' description: >- Customer-facing model identifier for the charge, using the same resolution as `by_model`. Null when the work bills no model, or bills one that is not offered as a customer-facing model. operation: type: string project_id: anyOf: - type: string - type: 'null' scene_id: anyOf: - type: string - type: 'null' source_id: type: string required: - id - billing_surface - operation - source_id - credits_charged - created_at title: UsageChargeSummary type: object ApiError: additionalProperties: false description: Concrete error returned inside `ApiErrorEnvelope.error`. properties: code: description: >- Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not `message`. type: string message: description: Human-readable summary. Not stable; do not parse. type: string param: anyOf: - type: string - type: 'null' description: Offending request field (dot-path), if applicable. request_id: description: Echo of the `X-Request-Id` response header for support. type: string type: $ref: '#/components/schemas/ErrorType' required: - type - code - message - request_id title: ApiError type: object ErrorType: description: |- Top-level error categories. Maps roughly to HTTP status. `code` (a free-form lower_snake_case string on `ApiError`) is the machine-readable subcode SDKs should switch on; `type` is the broad category. enum: - invalid_request - authentication - permission - not_found - conflict - unprocessable - rate_limit - quota_exceeded - internal - service_unavailable title: ErrorType type: string securitySchemes: ApiKey: bearerFormat: sk_live_* description: >- Live API key minted in the dashboard. Pass as `Authorization: Bearer sk_live_…`. Keys are scoped to a single environment (staging / prod). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.