> ## 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: [] 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: Blocking talking-avatar video generation from uploaded audio. name: videos - 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 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_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_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 UTC 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 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 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 ````