> ## 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. # Retrieve Speech-to-Video Session Usage > Retrieve your speech-to-video usage per day. A session counts on the day it was created, in UTC, once it has ended. The figures are seconds as your plan counts them, and cover every workspace of your organization, so only an API key of the default workspace can read them. Agent conversations and text-to-video are not included. The days are UTC calendar days, so they do not line up with your billing period; Retrieve Usage gives the usage of your billing period. A range spans at most 366 days and 10,000 sessions; split a busier range into shorter ones. ## OpenAPI ````yaml /openapi.json get /v1/usage/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. Exhausting the usage limit returns HTTP `402`, and reaching the concurrency limit returns HTTP `429`. 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. - name: Usage description: Retrieve how much of your plan your organization has used. paths: /v1/usage/sessions: get: tags: - Usage summary: Retrieve Speech-to-Video Session Usage description: >- Retrieve your speech-to-video usage per day. A session counts on the day it was created, in UTC, once it has ended. The figures are seconds as your plan counts them, and cover every workspace of your organization, so only an API key of the default workspace can read them. Agent conversations and text-to-video are not included. The days are UTC calendar days, so they do not line up with your billing period; Retrieve Usage gives the usage of your billing period. A range spans at most 366 days and 10,000 sessions; split a busier range into shorter ones. operationId: get_session_usage_v1_usage_sessions_get parameters: - name: start in: query required: true schema: type: string format: date description: First day to report, in UTC (YYYY-MM-DD). title: Start description: First day to report, in UTC (YYYY-MM-DD). - name: end in: query required: true schema: type: string format: date description: Last day to report, in UTC (YYYY-MM-DD). title: End description: Last day to report, in UTC (YYYY-MM-DD). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SessionUsageResponse' '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' '402': description: >- The plan's usage limit has been reached, or the requested feature requires a plan upgrade. content: application/json: examples: usage: summary: Usage limit reached value: detail: >- You have reached your usage limit. Please upgrade your plan or enable usage-based billing. 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' '403': description: >- The API key is valid but not permitted to perform this action, because the resource belongs to someone else. content: application/json: example: detail: You do not have permission to access this resource. 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: >- The plan's limit on the number of concurrent sessions has been reached. content: application/json: example: 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: SessionUsageResponse: properties: data: items: $ref: '#/components/schemas/DailySessionUsage' type: array title: Data description: Every day of the requested range, oldest first. type: object required: - data title: SessionUsageResponse description: Speech-to-video usage per day. 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. DailySessionUsage: properties: date: type: string title: Date description: Day in UTC, in YYYY-MM-DD format. examples: - '2026-10-01' used_seconds: type: integer title: Used Seconds description: Usage of the sessions created that day. examples: - 1830 type: object required: - date - used_seconds title: DailySessionUsage description: Usage of the speech-to-video sessions created on one day. securitySchemes: APIKeyHeader: type: apiKey description: Your Beyond Presence API Key. in: header name: x-api-key ```` ## Related topics - [Retrieve Speech-to-Video Session](https://docs.bey.dev/api-reference/speech-to-video-sessions/retrieve-speech-to-video-session.md) - [Create Speech-to-Video Session](https://docs.bey.dev/api-reference/speech-to-video-sessions/create-speech-to-video-session.md) - [List Speech-to-Video Sessions](https://docs.bey.dev/api-reference/speech-to-video-sessions/list-speech-to-video-sessions.md) - [Retrieve Usage](https://docs.bey.dev/api-reference/usage/retrieve-usage.md) - [Roadmap](https://docs.bey.dev/learn/roadmap.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.