bithuman-ai Runtime sessions API
List live sessions, read a transcript, end or terminate a session, revoke every runtime key: [https://docs.bithuman.ai/api/runtime-sessions](https://docs.bithuman.ai/api/runtime-sessions).
List live sessions, read a transcript, end or terminate a session, revoke every runtime key: [https://docs.bithuman.ai/api/runtime-sessions](https://docs.bithuman.ai/api/runtime-sessions).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bithuman-ai:bithuman-ai-runtime-sessions-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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