> ## 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 the usage of each speech-to-video session.

Lists the sessions created in the range, in UTC days, that have started
and 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/<agent-id>`. 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: <your-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 the usage of each speech-to-video session.

        Lists the sessions created in the range, in UTC days, that have started
        and 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: Earliest day a listed session was created, in UTC (YYYY-MM-DD).
            title: Start
          description: Earliest day a listed session was created, in UTC (YYYY-MM-DD).
        - name: end
          in: query
          required: true
          schema:
            type: string
            format: date
            description: Latest day a listed session was created, in UTC (YYYY-MM-DD).
            title: End
          description: Latest day a listed session was created, 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/SessionUsage'
          type: array
          title: Data
          description: Every ended session of the requested range, newest first.
      type: object
      required:
        - data
      title: SessionUsageResponse
      description: Speech-to-video usage per session.
    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.
    SessionUsage:
      properties:
        id:
          type: string
          title: Id
          description: ID of the session.
          examples:
            - 01234567-89ab-cdef-0123-456789abcdef
        avatar_id:
          type: string
          title: Avatar Id
          description: ID of the avatar of the session.
          examples:
            - 01234567-89ab-cdef-0123-456789abcdef
        started_at:
          type: string
          title: Started At
          description: Time the avatar started in the room in ISO 8601 format.
          examples:
            - '2026-10-01T09:00:00+00:00'
        ended_at:
          type: string
          title: Ended At
          description: Time the session ended in ISO 8601 format.
          examples:
            - '2026-10-01T09:30:30+00:00'
        used_seconds:
          type: integer
          title: Used Seconds
          description: >-
            Usage billed for the session: from the time the avatar started in
            the room until the session ended.
          examples:
            - 1830
      type: object
      required:
        - id
        - avatar_id
        - started_at
        - ended_at
        - used_seconds
      title: SessionUsage
      description: Usage of one speech-to-video session.
  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)
- [Roadmap](https://docs.bey.dev/learn/roadmap.md)
- [Concurrency & Quotas](https://docs.bey.dev/production/concurrency.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.