> ## 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. # List sessions > List sessions for the calling org, newest first. Repeatable `status` filters OR together; the group aliases `active` and `terminal` expand to the underlying status set. `created_after` / `created_before` accept ISO-8601 UTC. Paginate with `limit` + `starting_after=`. ## OpenAPI ````yaml /openapi.json get /v1/sessions 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/sessions: get: tags: - sessions summary: List sessions description: >- List sessions for the calling org, newest first. Repeatable `status` filters OR together; the group aliases `active` and `terminal` expand to the underlying status set. `created_after` / `created_before` accept ISO-8601 UTC. Paginate with `limit` + `starting_after=`. operationId: list_sessions parameters: - description: >- Repeatable filter. Accepts a `SessionStatus` value or the aliases `active` / `terminal`. Multiple values OR together. in: query name: status required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Repeatable filter. Accepts a `SessionStatus` value or the aliases `active` / `terminal`. Multiple values OR together. title: Status - description: Filter to sessions referencing this avatar. in: query name: avatar_id required: false schema: anyOf: - type: string - type: 'null' description: Filter to sessions referencing this avatar. title: Avatar Id - description: Lower bound, inclusive. ISO-8601 UTC. in: query name: created_after required: false schema: anyOf: - format: date-time type: string - type: 'null' description: Lower bound, inclusive. ISO-8601 UTC. title: Created After - description: Upper bound, exclusive. ISO-8601 UTC. in: query name: created_before required: false schema: anyOf: - format: date-time type: string - type: 'null' description: Upper bound, exclusive. ISO-8601 UTC. title: Created Before - description: Page size. Default 20, max 100. in: query name: limit required: false schema: default: 20 description: Page size. Default 20, max 100. maximum: 100 minimum: 1 title: Limit type: integer - description: Pagination cursor — a `sess_…` id from a previous page. in: query name: starting_after required: false schema: anyOf: - type: string - type: 'null' description: Pagination cursor — a `sess_…` id from a previous page. title: Starting After responses: '200': content: application/json: schema: $ref: '#/components/schemas/SessionList' description: Successful Response '400': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Unknown status filter value. '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: SessionList: additionalProperties: false description: Cursor-paginated list of sessions. examples: - data: [] has_more: false object: list properties: data: items: $ref: '#/components/schemas/Session' type: array has_more: type: boolean next_cursor: anyOf: - type: string - type: 'null' description: Pass as `starting_after` on the next request to continue. object: const: list default: list type: string required: - data - has_more title: SessionList 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 Session: additionalProperties: false description: Public session resource — what `GET /v1/sessions/{id}` returns. examples: - avatar_id: av_stock_001 billing_surface: api created_at: '2026-05-25T19:00:00.123Z' first_frame_at: '2026-05-25T19:00:02.001Z' id: sess_01HXY5K8E7QYG3X8Z6N9R7S0VR idle_timeout_seconds: 30 max_duration_seconds: 600 metadata: customer_session_id: abc123 object: session quality: standard started_at: '2026-05-25T19:00:01.456Z' status: running transport: audio_source: data_stream room_name: demo-room type: livekit url: wss://my-app.livekit.cloud usage: billable_seconds: 12 frames: 300 properties: avatar_id: type: string billing_surface: $ref: '#/components/schemas/BillingSurface' default: api description: Service that created the session. Use this to group usage reporting. created_at: format: date-time type: string ended_at: anyOf: - format: date-time type: string - type: 'null' failed_at: anyOf: - format: date-time type: string - type: 'null' failure: anyOf: - $ref: '#/components/schemas/SessionFailure' - type: 'null' first_frame_at: anyOf: - format: date-time type: string - type: 'null' description: Set on `session.first_frame`. id: description: '`sess_…` prefixed ULID.' type: string idle_timeout_seconds: type: integer max_duration_seconds: type: integer metadata: additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean - type: 'null' type: object object: const: session default: session type: string quality: $ref: '#/components/schemas/QualityTier' started_at: anyOf: - format: date-time type: string - type: 'null' description: Set when worker emits `session.starting`. status: $ref: '#/components/schemas/SessionStatus' transport: discriminator: mapping: livekit: $ref: '#/components/schemas/LiveKitTransportConfig' pipecat: $ref: '#/components/schemas/PipecatTransportConfig' websocket: $ref: '#/components/schemas/WebSocketTransportConfig' propertyName: type oneOf: - $ref: '#/components/schemas/LiveKitTransportConfig' - $ref: '#/components/schemas/WebSocketTransportConfig' - $ref: '#/components/schemas/PipecatTransportConfig' usage: $ref: '#/components/schemas/SessionUsage' required: - id - status - avatar_id - transport - quality - max_duration_seconds - idle_timeout_seconds - metadata - created_at title: Session 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 BillingSurface: description: Product surface that initiated a billable avatar session. enum: - api - playground - embed - share - public_demo - pipecat - video_generation title: BillingSurface type: string SessionFailure: additionalProperties: false description: Populated when `Session.status == failed`. properties: code: description: Stable lower_snake_case subcode. type: string message: description: Human-readable summary; not stable. type: string required: - code - message title: SessionFailure type: object QualityTier: description: Output quality tier. enum: - mock - lite - standard - pro title: QualityTier type: string SessionStatus: description: >- Public session lifecycle. Terminal states are `ended`, `failed`, `canceled`. `ending` is the graceful-drain state while a worker finishes publishing in-flight frames. enum: - created - queued - starting - running - ending - ended - failed - canceled title: SessionStatus type: string LiveKitTransportConfig: additionalProperties: false description: |- BYO LiveKit transport. The customer owns the room and mints `worker_token`; we never touch their LiveKit API key or secret. examples: - audio_source: data_stream room_name: demo-room type: livekit url: wss://my-app.livekit.cloud worker_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... properties: audio_source: $ref: '#/components/schemas/LiveKitAudioSource' default: data_stream description: How the worker receives audio. See LiveKitAudioSource. room_name: description: Name of the LiveKit room the worker should join. type: string subscribe_to_identity: anyOf: - type: string - type: 'null' description: >- When `audio_source=track`, pin to this participant. Ignored otherwise. synthetic_audio_if_no_input: default: false description: >- If True and no participant joins within 10 s, the worker falls back to a synthetic sine generator. Demo aid only; default off. type: boolean type: const: livekit default: livekit type: string url: description: Customer's LiveKit URL, e.g. `wss://my-app.livekit.cloud`. type: string worker_identity: default: protoface-worker description: Identity the worker presents inside the room. type: string worker_token: description: >- Short-lived JWT the customer mints authorizing our worker to join the room. **Write-only.** Never echoed back on read; `GET /v1/sessions/{id}.transport.worker_token` returns the string `"[redacted]"`. type: string writeOnly: true required: - url - room_name - worker_token title: LiveKitTransportConfig type: object PipecatTransportConfig: additionalProperties: false description: |- Reserved — BYO Pipecat transport. `POST /v1/sessions` still rejects `transport.type=pipecat`; use `POST /v1/pipecat/sessions` for the Protoface Pipecat video service. properties: type: const: pipecat default: pipecat type: string title: PipecatTransportConfig type: object WebSocketTransportConfig: additionalProperties: false description: |- Reserved — raw WebSocket transport. **Not yet available.** Listed in the schema so existing clients keep parsing future responses, but `POST /v1/sessions` rejects it today with `invalid_request` / `code=transport.unsupported`. properties: type: const: websocket default: websocket type: string title: WebSocketTransportConfig type: object SessionUsage: additionalProperties: false description: |- Live usage counters embedded in the Session resource. Eventually-consistent — lags the latest worker heartbeat by up to one interval. Canonical billing data lives in `UsageEvent`. properties: billable_seconds: minimum: 0 type: integer frames: minimum: 0 type: integer required: - billable_seconds - frames title: SessionUsage 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 LiveKitAudioSource: description: |- How the LiveKit worker receives audio from the room. Use `data_stream` with the LiveKit Agents plugin. Use `track` only for custom integrations that publish audio tracks directly. enum: - data_stream - track title: LiveKitAudioSource 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 ````