> ## 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 runs ## OpenAPI ````yaml /openapi.json get /v1/runs 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/runs: get: tags: - runs summary: List runs operationId: listRuns parameters: - in: query name: limit required: false schema: default: 20 maximum: 100 minimum: 1 title: Limit type: integer - in: query name: starting_after required: false schema: anyOf: - maxLength: 40 type: string - type: 'null' title: Starting After responses: '200': content: application/json: schema: $ref: '#/components/schemas/RunList' description: Successful Response '402': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: The organization has insufficient credits for this run. '403': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: The API key's scopes do not permit this operation. '409': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: The request conflicts with the current state of the run. '422': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Request body or parameters failed validation. '429': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: >- Rate limit or queue capacity reached. Retry after the indicated delay. security: - ApiKey: [] components: schemas: RunList: properties: data: items: $ref: '#/components/schemas/RunView' type: array has_more: type: boolean next_cursor: anyOf: - type: string - type: 'null' object: const: list default: list type: string required: - data - has_more - next_cursor title: RunList 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 RunView: description: >- One finished or in-flight run. `video` / `image` / `audio` are a convenience projection: each carries the sole output of that modality when the run produced exactly one, which is the shape most clients read. `outputs` is the complete record and is the only place multi-part results, text, and structured data appear. The modality to field-name mapping is a platform convention, not a per-model fact. properties: audio: anyOf: - $ref: '#/components/schemas/RunFileView' - type: 'null' completed_at: anyOf: - format: date-time type: string - type: 'null' created_at: format: date-time type: string credits: anyOf: - $ref: '#/components/schemas/RunCreditsView' - type: 'null' error: anyOf: - $ref: '#/components/schemas/RunErrorView' - type: 'null' external_id: anyOf: - type: string - type: 'null' id: type: string image: anyOf: - $ref: '#/components/schemas/RunFileView' - type: 'null' metadata: additionalProperties: true type: object model: type: string model_revision: type: string object: const: run default: run type: string operation: type: string outputs: items: $ref: '#/components/schemas/RunOutputView' type: array progress: type: integer started_at: anyOf: - format: date-time type: string - type: 'null' status: type: string video: anyOf: - $ref: '#/components/schemas/RunFileView' - type: 'null' required: - id - model - model_revision - operation - status - progress - outputs - credits - error - metadata - external_id - created_at - started_at - completed_at title: RunView 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 RunFileView: properties: content_type: anyOf: - type: string - type: 'null' file_name: anyOf: - type: string - type: 'null' file_size: anyOf: - type: integer - type: 'null' url: type: string required: - url - content_type - file_name - file_size title: RunFileView type: object RunCreditsView: properties: charged: type: integer pricing_version: type: string reserved: type: integer required: - pricing_version - reserved - charged title: RunCreditsView type: object RunErrorView: properties: code: type: string message: type: string required: - code - message title: RunErrorView type: object RunOutputView: properties: asset_id: anyOf: - type: string - type: 'null' data: anyOf: - additionalProperties: true type: object - type: 'null' file: anyOf: - $ref: '#/components/schemas/RunFileView' - type: 'null' modality: type: string role: type: string text: anyOf: - type: string - type: 'null' type: enum: - text - asset - data type: string required: - role - modality - type title: RunOutputView 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 ````