> ## 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 Conversations > List conversations managed by your agents. Returns a cursor-paginated list of conversations across all of your agents, most recent first. ## OpenAPI ````yaml /openapi.json get /v1/conversations 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/conversations: get: tags: - Agent Conversations summary: List Conversations description: |- List conversations managed by your agents. Returns a cursor-paginated list of conversations across all of your agents, most recent first. operationId: list_conversations_v1_conversations_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 Conversations content: application/json: schema: $ref: '#/components/schemas/Page_ConversationResponse_' '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_ConversationResponse_: anyOf: - $ref: '#/components/schemas/HasMorePage_ConversationResponse_' - $ref: '#/components/schemas/NoMorePage_ConversationResponse_' 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_ConversationResponse_: properties: data: items: $ref: '#/components/schemas/ConversationResponse' 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[ConversationResponse] NoMorePage_ConversationResponse_: properties: data: items: $ref: '#/components/schemas/ConversationResponse' 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[ConversationResponse] ConversationResponse: properties: id: type: string title: Id description: Unique identifier of the object in the database. examples: - 01234567-89ab-cdef-0123-456789abcdef agent_id: type: string title: Agent Id description: ID of agent managing the conversation. user_name: anyOf: - type: string - type: 'null' title: User Name description: Name of the user. user_email: anyOf: - type: string - type: 'null' title: User Email description: Email of the user. tags: additionalProperties: type: string maxLength: 100 minLength: 1 propertyNames: maxLength: 30 minLength: 1 type: object maxProperties: 10 title: Tags description: Tags for the conversation. status: $ref: '#/components/schemas/ConversationStatus' type: object required: - id - agent_id - status title: ConversationResponse description: Response model for a conversation. ConversationStatus: oneOf: - $ref: '#/components/schemas/ToStartConversationStatus' - $ref: '#/components/schemas/OngoingConversationStatus' - $ref: '#/components/schemas/CompletedConversationStatus' discriminator: propertyName: type mapping: completed: $ref: '#/components/schemas/CompletedConversationStatus' ongoing: $ref: '#/components/schemas/OngoingConversationStatus' to_start: $ref: '#/components/schemas/ToStartConversationStatus' ToStartConversationStatus: properties: type: type: string const: to_start title: Type default: to_start type: object title: ToStartConversationStatus description: Status for conversation that has not yet started. OngoingConversationStatus: 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: OngoingConversationStatus description: Status for conversation that is currently ongoing. CompletedConversationStatus: 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: CompletedConversationStatus description: Status for conversation that has completed. securitySchemes: APIKeyHeader: type: apiKey description: Your Beyond Presence API Key. in: header name: x-api-key ```` ## Related topics - [List Conversation Messages](/api-reference/agent-conversations/list-conversation-messages.md) - [Conversational Video Agents](/concepts/agents/index.md) - [Managed Agent Quickstart](/get-started/quickstart/managed-agent.md) - [List Agents](/api-reference/agents/list-agents.md) - [List Avatars](/api-reference/avatars/list-avatars.md)