> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telleo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get usage

> Calls, connected calls, talk time and credits charged per day. Credits come from your account's ledger; test calls are not included.

Scope: `calls:read`.



## OpenAPI

````yaml /api-reference/openapi.json get /usage
openapi: 3.1.0
info:
  title: Telleo API
  version: 1.2.0
  description: >-
    Start AI phone calls, or connect your counsellors to contacts, from your own
    systems and get each call's outcome back.
servers:
  - url: https://api.telleo.ai/v1
security:
  - ApiKey: []
tags:
  - name: Calls
  - name: Batches
  - name: Agents
  - name: Human calls
  - name: Credits
  - name: Webhook
paths:
  /usage:
    get:
      tags:
        - Credits
      summary: Get usage
      description: >-
        Calls, connected calls, talk time and credits charged per day. Credits
        come from your account's ledger; test calls are not included.


        Scope: `calls:read`.
      operationId: getUsage
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: 'First day, `YYYY-MM-DD`. Default: 6 days before `to`.'
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: 'Last day (included). Default: today. At most 92 days after `from`.'
        - name: timezone
          in: query
          schema:
            type: string
            default: UTC
          description: IANA zone the days are cut in, e.g. `Asia/Kolkata`.
        - name: source
          in: query
          schema:
            type: string
            enum:
              - api
              - all
            default: api
          description: >-
            `api`: calls placed through the API. `all`: every AI call on your
            account.
      responses:
        '200':
          description: Usage per day.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          description: A parameter is not valid.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    error:
                      code: invalid_request
                      message: A usage range is at most 92 days.
                      request_id: req_8f2c1a7e
        '401':
          description: The key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error:
                      code: missing_api_key
                      message: Send your API key in the X-API-Key header.
                      request_id: req_8f2c1a7e
                invalid_api_key:
                  value:
                    error:
                      code: invalid_api_key
                      message: This API key is not valid.
                      request_id: req_8f2c1a7e
        '429':
          description: Too many requests for this key.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests. Retry after 12 seconds.
                      request_id: req_8f2c1a7e
components:
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  schemas:
    Usage:
      type: object
      properties:
        object:
          type: string
          const: usage
        source:
          type: string
          enum:
            - api
            - all
        from:
          type: string
        to:
          type: string
        timezone:
          type: string
        totals:
          type: object
          properties:
            calls:
              type: integer
            connected:
              type: integer
            talk_seconds:
              type: integer
            credits:
              type: number
            calls_not_yet_billed:
              type: integer
              description: >-
                Calls with a charge still to be made (call minutes, or AI
                minutes once the outcome is processed). Calls that are never
                charged are not counted.
        days:
          type: array
          items:
            $ref: '#/components/schemas/UsageDay'
        human_calls:
          type: object
          description: >-
            Human (counsellor) calls in the same range: with `source=api` those
            placed through `POST /human-calls`, with `source=all` every outbound
            counsellor call placed on Vacademy Voice, Exotel or Airtel (uploaded
            recordings of calls made elsewhere are not counted). Only Vacademy
            Voice talk time is charged.
          properties:
            totals:
              type: object
              properties:
                calls:
                  type: integer
                connected:
                  type: integer
                talk_seconds:
                  type: integer
                credits:
                  type: number
                calls_not_yet_billed:
                  type: integer
            days:
              type: array
              items:
                $ref: '#/components/schemas/UsageDay'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable code. Branch on this, not on the message.
              example: invalid_request
            message:
              type: string
              description: A sentence you can log or show to an operator.
            request_id:
              type: string
              description: Quote this when you contact support.
            details:
              type: object
              additionalProperties: true
              description: >-
                Extra context, e.g. `errors: [{field, message}]` for validation
                errors or `call_id` for conflicts.
    UsageDay:
      type: object
      properties:
        date:
          type: string
          example: '2026-10-01'
        calls:
          type: integer
        connected:
          type: integer
        talk_seconds:
          type: integer
        credits:
          type: number
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your AI calling API key (`vak_call_…`). `Authorization: Bearer <key>`
        also works.

````

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