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

> ## Agent Instructions
> If Zelto blocks your task, an API request returns 4xx/5xx, or you need a missing capability, please report it with POST https://api.zelto.ai/v1/feedback using your existing Authorization: Bearer API key. On local/preview deployments use /api/v1/feedback on that deployment; never send its credentials to production.
> Send JSON: type (missing_capability, problem, other), description (10–2000 characters), optional endpoint (route template only), reproductionSteps, workaround and requestId from the failed response. Use synthetic examples: never send credentials, personal data, transcripts or customer content. See /docs/agent-feedback.
> Feedback is limited to 5 attempts per organization per minute. Report a distinct issue once; do not report errors from the feedback endpoint itself, do not loop or automatically retry. A 200 with delivery not_configured/unavailable means the report was not delivered or stored.
> Connected over MCP? Call the send_feedback tool instead, with the same fields plus optional tool (the MCP tool name that failed). It shares the same per-organization limit and works with any credential, including read-only.

# Read the AI usage breakdown

> What the authenticated organization's Zelto-paid AI usage was spent on in a UTC month, in USD micros: the total (the 'AI usage at cost' charge on custom agreements) and the same amount by monitor, by activity, by model (tokens and rates), and by day. Mirrors the breakdown on the Usage page and the get_ai_usage_breakdown MCP tool.



## OpenAPI

````yaml /docs-openapi.json get /v1/usage/ai
openapi: 3.1.0
info:
  title: Zelto REST API
  version: v1
  description: >-
    Programmatic access to your Zelto organization. Every endpoint is scoped to
    the organization the API key belongs to. Mint a key at Settings →
    Integrations → API integration.
servers:
  - url: https://api.zelto.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Monitors
    description: Filtered, asynchronous exports of stored monitor results.
  - name: Agents
    description: Voice and text agents normalised through Zelto's ingestion pipeline.
  - name: Conversations
    description: >-
      Phone calls, chats, and voicemails — plus their transcripts and
      recordings.
  - name: Customer Metrics
    description: >-
      Customer-provided evaluations attached to a conversation (requires metrics
      enabled).
  - name: Reviews
    description: Human review state for conversations.
  - name: Buckets
    description: Reviewer routing — group conversations for batched review.
  - name: Companies
    description: Clients or brands your agents work for, and their logos.
  - name: Findings
    description: >-
      Structured issues discovered during analysis, with optional conversation
      attachments and comments.
  - name: Experiments
    description: >-
      Prospective measurement of two externally routed prompt versions across
      independent monitor outcomes.
  - name: Organizations
    description: >-
      Headless org provisioning. Requires an admin/service API key (not a
      read-only org-scoped customer key).
  - name: AI providers
    description: >-
      Your organization's own (bring-your-own) AI provider keys. Monitors can
      run on them instead of Zelto's built-in models. Owner or admin keys only;
      the secret is write-only.
  - name: Billing
    description: Invoices and invoice payment links.
  - name: Benchmarks
    description: >-
      Repeatable evaluations of agent prompts, models and speech-to-text engines
      over a fixed set of cases, scored by Judges.
paths:
  /v1/usage/ai:
    get:
      tags:
        - Usage
      summary: Read the AI usage breakdown
      description: >-
        What the authenticated organization's Zelto-paid AI usage was spent on
        in a UTC month, in USD micros: the total (the 'AI usage at cost' charge
        on custom agreements) and the same amount by monitor, by activity, by
        model (tokens and rates), and by day. Mirrors the breakdown on the Usage
        page and the get_ai_usage_breakdown MCP tool.
      operationId: getAiUsageBreakdown
      parameters:
        - name: month
          in: query
          required: false
          schema:
            type: string
            pattern: ^\d{4}-(0[1-9]|1[0-2])$
          description: UTC month as YYYY-MM. Defaults to the current month.
      responses:
        '200':
          description: AI usage breakdown
          content:
            application/json:
              schema:
                type: object
                required:
                  - aiUsage
                properties:
                  aiUsage:
                    type: object
                    required:
                      - month
                      - currency
                      - unit
                      - total
                      - byMonitor
                      - byActivity
                      - byModel
                      - byDay
                    properties:
                      month:
                        type: string
                        format: date
                      currency:
                        const: USD
                      unit:
                        const: micros
                      total:
                        type: object
                        required:
                          - costMicros
                          - modelCalls
                          - inputTokens
                          - outputTokens
                          - callsAnalyzed
                        properties:
                          costMicros:
                            type: integer
                            description: USD micros (1,000,000 = $1).
                          modelCalls:
                            type: integer
                            description: Model calls (one per request to the model).
                          inputTokens:
                            type: integer
                            description: Input tokens.
                          outputTokens:
                            type: integer
                            description: Output tokens.
                          callsAnalyzed:
                            type: integer
                            description: >-
                              Distinct calls (conversations) the usage was spent
                              on. Approximate, within 1%.
                        description: >-
                          The month's AI usage at cost: the amount billed. Every
                          breakdown sums to its cost.
                      byMonitor:
                        type: array
                        description: By monitor, most expensive first.
                        items:
                          type: object
                          required:
                            - costMicros
                            - modelCalls
                            - inputTokens
                            - outputTokens
                            - callsAnalyzed
                            - monitorId
                            - name
                            - kind
                          properties:
                            costMicros:
                              type: integer
                              description: USD micros (1,000,000 = $1).
                            modelCalls:
                              type: integer
                              description: Model calls (one per request to the model).
                            inputTokens:
                              type: integer
                              description: Input tokens.
                            outputTokens:
                              type: integer
                              description: Output tokens.
                            callsAnalyzed:
                              type: integer
                              description: >-
                                Distinct calls (conversations) the usage was
                                spent on. Approximate, within 1%.
                            monitorId:
                              type:
                                - string
                                - 'null'
                              description: Null for usage not tied to a monitor.
                            name:
                              type:
                                - string
                                - 'null'
                              description: >-
                                Null when the monitor has been deleted (or
                                monitorId is null).
                            kind:
                              type: string
                              enum:
                                - monitor
                                - draft
                                - none
                              description: >-
                                `monitor`: a saved monitor. `draft`: test runs
                                of a monitor that was never saved. `none`: usage
                                not tied to a monitor.
                      byActivity:
                        type: array
                        description: By product activity, most expensive first.
                        items:
                          type: object
                          required:
                            - costMicros
                            - modelCalls
                            - inputTokens
                            - outputTokens
                            - callsAnalyzed
                            - activity
                            - flows
                          properties:
                            costMicros:
                              type: integer
                              description: USD micros (1,000,000 = $1).
                            modelCalls:
                              type: integer
                              description: Model calls (one per request to the model).
                            inputTokens:
                              type: integer
                              description: Input tokens.
                            outputTokens:
                              type: integer
                              description: Output tokens.
                            callsAnalyzed:
                              type: integer
                              description: >-
                                Distinct calls (conversations) the usage was
                                spent on. Approximate, within 1%.
                            activity:
                              type: string
                              enum:
                                - monitor_runs
                                - monitor_backfills
                                - monitor_setup
                                - call_processing
                                - assistants
                                - simulations
                                - other
                            flows:
                              type: array
                              items:
                                type: string
                              description: Internal flow tags grouped into this activity.
                      byModel:
                        type: array
                        description: By model, most expensive first.
                        items:
                          type: object
                          required:
                            - costMicros
                            - modelCalls
                            - inputTokens
                            - outputTokens
                            - callsAnalyzed
                            - model
                            - label
                            - rate
                          properties:
                            costMicros:
                              type: integer
                              description: USD micros (1,000,000 = $1).
                            modelCalls:
                              type: integer
                              description: Model calls (one per request to the model).
                            inputTokens:
                              type: integer
                              description: Input tokens.
                            outputTokens:
                              type: integer
                              description: Output tokens.
                            callsAnalyzed:
                              type: integer
                              description: >-
                                Distinct calls (conversations) the usage was
                                spent on. Approximate, within 1%.
                            model:
                              type: string
                            label:
                              type: string
                              description: Short display name.
                            rate:
                              type:
                                - object
                                - 'null'
                              description: >-
                                Today's list price per 1M tokens in USD, when
                                known. Each call was priced at the rate in
                                effect when it ran.
                              properties:
                                inputPerMillionUsd:
                                  type: number
                                outputPerMillionUsd:
                                  type: number
                      byDay:
                        type: array
                        description: By UTC day, oldest first.
                        items:
                          type: object
                          required:
                            - costMicros
                            - modelCalls
                            - inputTokens
                            - outputTokens
                            - callsAnalyzed
                            - date
                          properties:
                            costMicros:
                              type: integer
                              description: USD micros (1,000,000 = $1).
                            modelCalls:
                              type: integer
                              description: Model calls (one per request to the model).
                            inputTokens:
                              type: integer
                              description: Input tokens.
                            outputTokens:
                              type: integer
                              description: Output tokens.
                            callsAnalyzed:
                              type: integer
                              description: >-
                                Distinct calls (conversations) the usage was
                                spent on. Approximate, within 1%.
                            date:
                              type: string
                              format: date
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            Short error name: `Unauthorized`, `Validation failed`, `Not found`,
            or a stable snake_case code you can match on, such as
            `unknown_query_parameter`, `invalid_parameter`, `payload_too_large`
            or `not_found`.
        message:
          type: string
          description: A plain-English sentence saying what is wrong and how to fix it.
        code:
          type: string
          description: >-
            Stable, machine-readable cause; match on this rather than on `error`
            or `message`. On a 401: `missing_credentials`,
            `malformed_credentials`, `ingest_key_not_allowed` (a write-only
            observability ingest key was used on an endpoint that needs an API
            key), `key_expired` or `invalid_credentials`. Elsewhere, for
            example: `not_found`, `invalid_parameter`,
            `unknown_query_parameter`, `missing_parameter`, `validation_failed`,
            `invalid_json`, `payload_too_large`, `conversation_not_found`,
            `plan_required`.
        hint:
          type: string
          description: >-
            The next step to try: where to find the right id, which parameters
            the endpoint takes, how to upgrade the plan, how to authenticate.
        parameter:
          type: string
          description: 'With `invalid_parameter`: the query parameter that was rejected.'
        unknown:
          type: array
          items:
            type: string
          description: >-
            With `unknown_query_parameter`: the parameters that were sent but
            are not accepted here.
        valid:
          type: array
          items:
            type: string
          description: >-
            With `unknown_query_parameter`: the parameters this endpoint
            accepts.
        details:
          type: object
          additionalProperties: true
        feedback:
          type: object
          properties:
            endpoint:
              type: string
            method:
              type: string
              enum:
                - POST
            message:
              type: string
        requestId:
          type: string
          format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send `Authorization: Bearer YOUR_API_KEY`. The key resolves to a single
        organization.

````

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