bithuman-ai Runtime sessions API

openapi: 3.2.0
info:
  title: Bithuman Ai Runtime sessions API
  version: '1.0'
  contact:
    name: bitHuman Support
    url: https://www.bithuman.ai/discord
  x-logo:
    url: https://docs.bithuman.ai/bithuman-mark.png
  description: 'Operations tagged Runtime sessions across 2 of this provider''s published API definitions: openapi.yaml, bithuman-ai-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bithuman.ai
  description: Production
security:
- apiSecret: []
tags:
- name: Runtime sessions
  description: 'List live sessions, read a transcript, end or terminate a session, revoke every runtime key: https://docs.bithuman.ai/api/runtime-sessions.'
paths:
  /v2/{user_id}/runtime-sessions:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: listRuntimeSessions
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl \"https://api.bithuman.ai/v2/$USER_ID/runtime-sessions?window=live\" \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
      summary: List sessions
      description: 'Your sessions plus live account KPIs (`active_count`,

        `live_burn_rate_cr_per_min`, `credits_this_hour`, account-wide over the

        last hour). A transient `500 UPSTREAM_ERROR` can be retried.'
      tags:
      - Runtime sessions
      parameters:
      - name: window
        in: query
        schema:
          type: string
          enum:
          - all
          - live
          - recent
          default: all
        description: '`live` (only running), `recent` (idle + ended), or `all`.'
      - name: kind
        in: query
        schema:
          type: string
          enum:
          - all
          - conversations
          - self_hosted
          default: all
        description: '`conversations` (cloud), `self_hosted`, or `all`.'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: Max sessions to return.
      responses:
        '200':
          description: KPIs and the filtered session list.
          content:
            application/json:
              example:
                success: true
                data:
                  active_count: 1
                  live_burn_rate_cr_per_min: 4
                  credits_this_hour: 52
                  sessions:
                  - id: a3f1c8e2-…-9b02
                    agent_code: agent_greeter
                    agent_name: Greeter
                    billing_type: usage_essence_2_model_cloud
                    key_alias: prod-server
                    room_name: room_a3f1c8e2
                    started: '2026-07-15T15:20:00Z'
                    last_seen: '2026-07-15T15:33:00Z'
                    minutes: 13.0
                    credits: 52
                    burn_rate_cr_per_min: 4
                    status: live
                    has_transcript: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: '`FORBIDDEN` — the `user_id` in the path is not yours.'
    servers:
    - url: https://api.bithuman.ai
      description: Production
  /v2/{user_id}/runtime-sessions/{session_id}/messages:
    parameters:
    - $ref: '#/components/parameters/UserId'
    - $ref: '#/components/parameters/SessionId'
    get:
      operationId: getRuntimeSessionMessages
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl \"https://api.bithuman.ai/v2/$USER_ID/runtime-sessions/a3f1c8e2-…/messages\" \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
      summary: Read a transcript
      description: 'The conversation, oldest first. Only cloud voice and chat sessions

        record a transcript; self-hosted sessions return `messages: []`.'
      tags:
      - Runtime sessions
      responses:
        '200':
          description: The transcript.
          content:
            application/json:
              example:
                success: true
                data:
                  session_id: a3f1c8e2-…
                  agent_code: agent_greeter
                  started: '2026-07-15T15:20:00Z'
                  ended: '2026-07-15T15:33:00Z'
                  live: true
                  messages:
                  - timestamp: '2026-07-15T15:20:03Z'
                    role: user
                    message: Hi there
                  - timestamp: '2026-07-15T15:20:05Z'
                    role: assistant
                    message: Hello! How can I help?
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.bithuman.ai
      description: Production
  /v2/{user_id}/runtime-sessions/{session_id}/terminate:
    parameters:
    - $ref: '#/components/parameters/UserId'
    - $ref: '#/components/parameters/SessionId'
    post:
      operationId: terminateRuntimeSession
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl -X POST \"https://api.bithuman.ai/v2/$USER_ID/runtime-sessions/a3f1c8e2-…/terminate\" \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\" -H \"content-type: application/json\" -d '{}'\n"
      summary: Terminate a session
      description: 'Stops **one** session; never touches an API secret. The session stops

        counting toward your plan''s concurrent sessions at once.'
      tags:
      - Runtime sessions
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Free-text stop reason.
                  default: user-terminated
      responses:
        '200':
          description: Terminated.
          content:
            application/json:
              example:
                success: true
                data:
                  session_id: a3f1c8e2-…
                  closed: true
                  ended: true
                  self_hosted: false
                  note: Session ended — the avatar disconnected and the conversation closed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such session (or not yours).
    servers:
    - url: https://api.bithuman.ai
      description: Production
  /v2/{user_id}/runtime/revoke-all:
    parameters:
    - $ref: '#/components/parameters/UserId'
    post:
      operationId: revokeAllRuntimeKeys
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl -X POST \"https://api.bithuman.ai/v2/$USER_ID/runtime/revoke-all\" \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\" -H \"content-type: application/json\" -d '{}'\n"
      summary: Revoke all runtime keys
      description: 'The emergency stop: disables **every** runtime key on the account. Live

        sessions stop within one refresh cycle (about 5 minutes). It does not

        delete your API secrets; creating a new API secret clears the

        suspension.'
      tags:
      - Runtime sessions
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Free-text reason.
      responses:
        '200':
          description: Revoked.
          content:
            application/json:
              example:
                success: true
                data:
                  revoked: true
                  effective_in_seconds: 320
                  runtime_suspended: true
                  note: All runtime keys disabled. Creating a new API key restores runtime access.
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.bithuman.ai
      description: Production
  /v1/runtime-sessions/{session_id}:
    parameters:
    - $ref: '#/components/parameters/SessionId'
    get:
      operationId: getCloudAvatarSession
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl \"https://api.bithuman.ai/v1/runtime-sessions/$SESSION_ID\" \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
      summary: Read a cloud avatar session
      description: 'A cloud avatar

        session you started: `status` (`starting`, `live` or `ended`), times,

        `billed_seconds` and `credits` so far.'
      tags:
      - Runtime sessions
      responses:
        '200':
          description: The session.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such session (or not yours).
    servers:
    - url: https://api.bithuman.ai
      description: Production
  /v1/runtime-sessions/{session_id}/end:
    parameters:
    - $ref: '#/components/parameters/SessionId'
    post:
      operationId: endCloudAvatarSession
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl -X POST \"https://api.bithuman.ai/v1/runtime-sessions/$SESSION_ID/end\" \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
      summary: End a cloud avatar session
      description: 'Ends a cloud avatar

        you started, by the `session_id` its start returned. No body. Billing

        stops at this call and the concurrent-session slot frees at once.

        Calling it again returns the same answer and bills nothing.'
      tags:
      - Runtime sessions
      responses:
        '200':
          description: Ended. When `ended` is `false`, `note` says when the avatar leaves the room.
          content:
            application/json:
              example:
                session_id: cs_4f1c…
                status: ended
                agent_id: A23KSG5258
                model: essence-2
                room_name: my-room
                started_at: …
                ended_at: …
                billed_seconds: 131.2
                credits: 9
                ended: true
                slot_released: true
                note: 'Session ended: the avatar left the room and billing stopped.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such session (or not yours).
    servers:
    - url: https://api.bithuman.ai
      description: Production
components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Agent not found
              httpStatus: 404
            status: error
            status_code: 404
    Unauthorized:
      description: 'Authentication failed. `UNAUTHORIZED` when the `api-secret` header is

        present but invalid; `MISSING_AUTH` when it is absent. The HTTP status

        equals `status_code` (401).

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid API secret
              httpStatus: 401
            status: error
            status_code: 401
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: UNAUTHORIZED
            message:
              type: string
              example: Invalid API secret
            httpStatus:
              type: integer
              example: 401
            upgrade_url:
              type: string
              description: 'On `PLAN_REQUIRED`, `AGENT_LIMIT_REACHED` and `CONCURRENCY_LIMIT_REACHED` (403): where to choose a plan. Send the user there instead of retrying. See [Plan and credit refusals](https://docs.bithuman.ai/api/errors#plan-and-credit-refusals).'
              example: https://www.bithuman.ai/pricing
            topup_url:
              type: string
              description: 'On `INSUFFICIENT_BALANCE` (402): where to top up credits.'
              example: https://www.bithuman.ai/billing#credits
            details:
              type: object
              description: Code-specific fields. `CONCURRENCY_LIMIT_REACHED` sends `tier`, `cap`, `active` and `upgrade_url`.
              additionalProperties: true
        status:
          type: string
          example: error
        status_code:
          type: integer
          example: 401
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      schema:
        type: string
      description: Your own account id, from `GET /v1/me` (`data.user_id`). Another account's id returns `403 FORBIDDEN`.
    SessionId:
      name: session_id
      in: path
      required: true
      schema:
        type: string
      description: The session id.
  securitySchemes:
    apiSecret:
      type: apiKey
      name: api-secret
      in: header
      description: 'Your bitHuman API secret. Get one at

        [www.bithuman.ai/developer/api-keys](https://www.bithuman.ai/developer/api-keys).

        '
    bearerApiSecret:
      type: http
      scheme: bearer
      description: 'The same API secret, sent as `Authorization: Bearer <api-secret>`. Self-

        hosted runtimes send it this way; the classic `api-secret` header works

        on the same routes.

        '
x-refined-from:
- openapi.yaml
- bithuman-ai-openapi.yaml
x-tagGroups:
- name: Get started
  tags:
  - overview
  - quickstart
  - auth-guide
  - models
  - pricing
- name: Core concepts
  tags:
  - avatars-imx
  - audio-streaming
  - agent-lifecycle
- name: SDKs
  tags:
  - sdk-python
  - sdk-swift
  - cli
- name: Guides
  tags:
  - local-mode
  - building-avatars
- name: Deployment
  tags:
  - deploy-livekit
  - deploy-self-hosted
  - deploy-embed
- name: API reference
  tags:
  - Authentication
  - Agent Generation
  - Agent Management
  - Agent Context
  - Files
  - Dynamics
  - Embedding
  - Video
  - Billing
  - Account
  - Self-hosting
  - API secrets
  - Providers
  - Runtime sessions
  - Knowledge
  - Realtime
  - Status
  - Webhooks
- name: Resources
  tags:
  - community
  - changelog
  - support