> ## 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 Usage > Retrieve your organization's usage in the current billing period. All 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. Usage can take a few minutes to appear. ## OpenAPI ````yaml /openapi.json get /v1/usage 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: get: tags: - Usage summary: Retrieve Usage description: >- Retrieve your organization's usage in the current billing period. All 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. Usage can take a few minutes to appear. operationId: get_usage_v1_usage_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UsageResponse' '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: UsageResponse: properties: period_start: type: string title: Period Start description: Start of the billing period in ISO 8601 format. examples: - '2026-10-01T00:00:00+00:00' period_end: type: string title: Period End description: End of the billing period in ISO 8601 format, exclusive. examples: - '2027-01-01T00:00:00+00:00' included_seconds: type: integer title: Included Seconds description: Usage your plan includes in the billing period. examples: - 540000 used_seconds: type: integer title: Used Seconds description: Usage billed in the billing period, including overage. examples: - 432000 remaining_seconds: type: integer title: Remaining Seconds description: Usage your plan includes that is not used yet. examples: - 108000 overage_seconds: type: integer title: Overage Seconds description: >- Usage billed past what your plan includes. It only grows when usage-based billing is enabled. examples: - 0 type: object required: - period_start - period_end - included_seconds - used_seconds - remaining_seconds - overage_seconds title: UsageResponse description: Usage of the current billing period. 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. securitySchemes: APIKeyHeader: type: apiKey description: Your Beyond Presence API Key. in: header name: x-api-key ```` ## Related topics - [Retrieve Speech-to-Video Session Usage](https://docs.bey.dev/api-reference/usage/retrieve-speech-to-video-session-usage.md) - [Retrieve Avatar](https://docs.bey.dev/api-reference/avatars/retrieve-avatar.md) - [Retrieve Conversation](https://docs.bey.dev/api-reference/agent-conversations/retrieve-conversation.md) - [Retrieve Agent](https://docs.bey.dev/api-reference/agents/retrieve-agent.md) - [Retrieve Knowledge File](https://docs.bey.dev/api-reference/agent-knowledge-files/retrieve-knowledge-file.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.