> ## Documentation Index > Fetch the complete documentation index at: https://docs.bey.dev/llms.txt > Use this file to discover all available pages before exploring further. # List Speech-to-Video Sessions > List your speech-to-video sessions. Returns a cursor-paginated list of sessions, most recent first. ## OpenAPI ````yaml /openapi.json get /v1/sessions openapi: 3.1.0 info: title: Beyond Presence API summary: Create, configure, and run interactive real-time avatars. description: > The Beyond Presence API lets you build lifelike, real-time avatars. ## Starting a conversation with a Managed Agent There are two ways to put a user in front of one of your agents, and most integrations only need the first: 1. **Open the agent's managed room** at `https://bey.chat/`. This needs no API call at all and is available on every plan. Use the `Agent Conversations` endpoints afterwards to read status and transcripts. 2. **Drive the media session yourself** from a LiveKit client SDK, using `POST /v1/livekit-rooms` in the `Agent Integration` group to mint room credentials. This requires the Growth plan or above. ## Authentication Authenticate every request with your API key in the `x-api-key` header: ``` x-api-key: ``` You can create and manage API keys in the dashboard, and verify a key with `GET /v1/auth/verify`. ## Pagination List endpoints are cursor-paginated. Pass `limit` (1-50, default 10) to control the page size and `cursor` to fetch the next page. Each response includes a `next_cursor` when more results are available. ## Errors Errors return the appropriate HTTP status code with a JSON body containing a `detail` message with more information. ## Rate limits Usage and concurrency limits are tied to your plan and surfaced as HTTP `429` responses. version: 0.3.0 servers: - url: https://api.bey.dev security: [] tags: - name: Avatars description: Retrieve information about the avatars available to your account. - name: Agents description: Create and configure Managed Agents. - name: Agent Conversations description: >- Retrieve information about the conversations your Managed Agents have had, including their status, participants, and transcripts. - name: Agent Integration description: >- Primitives for embedding a Managed Agent in your own application with advanced cusotmization. **Most integrations do not need these.** - name: Agent Knowledge Files description: >- Manage the knowledge base documents your Managed Agents can draw on during a conversation. - name: Agents External APIs description: >- Store credentials for external services, such as an OpenAI-compatible LLM, so Managed Agents can reference them by ID. - name: Authentication description: Verify your API key. - name: Speech-to-Video Sessions description: >- Attach an avatar to a voice agent you build and run yourself. Prefer using the [LiveKit Plugin](https://docs.bey.dev/integrations/voice-agents/livekit) over calling these endpoints directly. paths: /v1/sessions: get: tags: - Speech-to-Video Sessions summary: List Speech-to-Video Sessions description: |- List your speech-to-video sessions. Returns a cursor-paginated list of sessions, most recent first. operationId: list_sessions_v1_sessions_get parameters: - name: limit in: query required: false schema: type: integer maximum: 50 exclusiveMinimum: 0 description: Maximum number of objects to return. default: 10 title: Limit description: Maximum number of objects to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination. title: Cursor description: Cursor for pagination. responses: '200': description: Paginated List of Speech-to-Video Sessions content: application/json: schema: $ref: '#/components/schemas/Page_SessionResponse_' '401': description: >- Authentication failed. The `x-api-key` header is missing or the provided API key is invalid. content: application/json: examples: missing: summary: Missing API key value: detail: API key is required. invalid: summary: Invalid API key value: detail: Invalid API key. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade. content: application/json: examples: permission: summary: Not permitted value: detail: You do not have permission to access this resource. plan: summary: Plan upgrade required value: detail: >- This feature is not available on your current plan. Please upgrade your plan. schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The requested resource does not exist or is not accessible with this API key. content: application/json: example: detail: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The request is malformed. `detail` lists each field that failed validation, where it was located, and why. content: application/json: example: detail: - loc: - body - name msg: Field required type: missing '429': description: >- A plan limit has been exceeded, either the usage limit or the number of concurrent sessions. content: application/json: examples: usage: summary: Usage limit exceeded value: detail: Usage limit exceeded. Please upgrade your plan. concurrency: summary: Concurrency limit exceeded value: detail: >- You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions. schema: $ref: '#/components/schemas/ErrorResponse' security: - APIKeyHeader: [] components: schemas: Page_SessionResponse_: anyOf: - $ref: '#/components/schemas/HasMorePage_SessionResponse_' - $ref: '#/components/schemas/NoMorePage_SessionResponse_' ErrorResponse: properties: detail: type: string title: Detail description: Human-readable description of the error. examples: - Invalid API key. type: object required: - detail title: ErrorResponse description: >- Standard error response body. Carries a single human-readable `detail` message describing what went wrong. This is the shape of every error response except validation errors (`422`), which instead return a list of per-field error objects. HasMorePage_SessionResponse_: properties: data: items: $ref: '#/components/schemas/SessionResponse' type: array title: Data description: List of objects. has_more: type: boolean const: true title: Has More description: Whether there are more objects to fetch. default: true next_cursor: type: string title: Next Cursor description: The cursor for the next page of objects. type: object required: - data - next_cursor title: HasMorePage[SessionResponse] NoMorePage_SessionResponse_: properties: data: items: $ref: '#/components/schemas/SessionResponse' type: array title: Data description: List of objects. has_more: type: boolean const: false title: Has More description: Whether there are more objects to fetch. default: false type: object required: - data title: NoMorePage[SessionResponse] SessionResponse: oneOf: - $ref: '#/components/schemas/LivekitSessionResponse' - $ref: '#/components/schemas/PipecatSessionResponse' discriminator: propertyName: transport mapping: livekit: $ref: '#/components/schemas/LivekitSessionResponse' pipecat: $ref: '#/components/schemas/PipecatSessionResponse' LivekitSessionResponse: properties: id: type: string title: Id description: Unique identifier of the object in the database. examples: - 01234567-89ab-cdef-0123-456789abcdef transport: type: string const: livekit title: Transport default: livekit avatar_id: type: string title: Avatar Id description: ID of avatar to use. examples: - 01234567-89ab-cdef-0123-456789abcdef status: $ref: '#/components/schemas/SessionStatus' url: type: string title: Url description: URL of LiveKit server the avatar worker should connect to. examples: - wss://.livekit.cloud type: object required: - id - avatar_id - status - url title: LivekitSessionResponse description: Response body for a LiveKit speech-to-video session. PipecatSessionResponse: properties: id: type: string title: Id description: Unique identifier of the object in the database. examples: - 01234567-89ab-cdef-0123-456789abcdef transport: type: string const: pipecat title: Transport default: pipecat avatar_id: type: string title: Avatar Id description: ID of avatar to use. examples: - 01234567-89ab-cdef-0123-456789abcdef status: $ref: '#/components/schemas/SessionStatus' url: type: string title: Url description: URL of Daily room the video bot should connect to. examples: - wss://.pipecat.cloud type: object required: - id - avatar_id - status - url title: PipecatSessionResponse description: Response body for a Pipecat speech-to-video session. SessionStatus: oneOf: - $ref: '#/components/schemas/SessionStatusToStart' - $ref: '#/components/schemas/SessionStatusOngoing' - $ref: '#/components/schemas/SessionStatusCompleted' discriminator: propertyName: type mapping: completed: $ref: '#/components/schemas/SessionStatusCompleted' ongoing: $ref: '#/components/schemas/SessionStatusOngoing' to_start: $ref: '#/components/schemas/SessionStatusToStart' SessionStatusToStart: properties: type: type: string const: to_start title: Type default: to_start type: object title: SessionStatusToStart description: Session that has not yet started. SessionStatusOngoing: properties: type: type: string const: ongoing title: Type default: ongoing started_at: type: string title: Started At description: Start time in ISO 8601 format. examples: - '2022-01-01T00:00:00Z' type: object required: - started_at title: SessionStatusOngoing description: Session that is currently ongoing. SessionStatusCompleted: properties: type: type: string const: completed title: Type default: completed started_at: type: string title: Started At description: Start time in ISO 8601 format. examples: - '2022-01-01T00:00:00Z' ended_at: type: string title: Ended At description: End time in ISO 8601 format. examples: - '2022-01-01T00:00:00Z' type: object required: - started_at - ended_at title: SessionStatusCompleted description: Session that has completed. securitySchemes: APIKeyHeader: type: apiKey description: Your Beyond Presence API Key. in: header name: x-api-key ```` ## Related topics - [Retrieve Speech-to-Video Session](/api-reference/speech-to-video-sessions/retrieve-speech-to-video-session.md) - [Create Speech-to-Video Session](/api-reference/speech-to-video-sessions/create-speech-to-video-session.md) - [Speech-to-Video Quickstart](/get-started/quickstart/speech-to-video.md) - [Speech-to-Video Integration for Voice Agents](/integrations/voice-agents/index.md) - [Roadmap](/learn/roadmap.md)