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

# Get Unit Usage Report

> Returns an organization's usage per billable unit (voice and text simulations, monitored calls, metric evaluations, triage, insights, Labs and AI metric building) with the credits billed for each, one column per calendar month (UTC) plus a total. The range may span at most 12 months. Each row's `values` maps a month (`YYYY-MM`) to a number; `other_credits` covers any remaining billed item and refunds are a negative row, so credit rows sum to `total_credits`. With an organization-scoped API key the organization comes from the key; with a user session pass `organization_id` (organization admins only). Pass `format=csv` to download the same table as CSV. Results may lag usage by up to 30 minutes.



## OpenAPI

````yaml get /test_framework/billing/unit-usage-report/
openapi: 3.1.0
info:
  title: Cekura API
  version: v1
  description: >-
    Complete API documentation for the Cekura platform. This API provides
    endpoints for testing, observing, and evaluating AI voice agents — including
    managing agents, running evaluators, defining metrics, and analyzing call
    quality.
servers:
  - url: https://api.cekura.ai
security: []
paths:
  /test_framework/billing/unit-usage-report/:
    get:
      tags:
        - test_framework
      summary: Get monthly usage and credits per billable unit
      description: >-
        Returns an organization's usage per billable unit (voice and text
        simulations, monitored calls, metric evaluations, triage, insights, Labs
        and AI metric building) with the credits billed for each, one column per
        calendar month (UTC) plus a total. The range may span at most 12 months.
        Each row's `values` maps a month (`YYYY-MM`) to a number;
        `other_credits` covers any remaining billed item and refunds are a
        negative row, so credit rows sum to `total_credits`. With an
        organization-scoped API key the organization comes from the key; with a
        user session pass `organization_id` (organization admins only). Pass
        `format=csv` to download the same table as CSV. Results may lag usage by
        up to 30 minutes.
      operationId: billing-unit-usage-report-retrieve
      parameters:
        - in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - json
          description: 'Response format. Default: json.'
        - in: query
          name: organization_id
          schema:
            type: integer
          description: >-
            Organization ID. Required for user sessions; ignored for
            organization-scoped API keys.
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: First day of the range (YYYY-MM-DD), inclusive.
          required: true
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: >-
            Last day of the range (YYYY-MM-DD), inclusive. At most 12 calendar
            months after `start_date`.
          required: true
        - in: query
          name: group_by
          schema:
            type: string
            enum:
              - month
          description: 'Period to group by. Default: month.'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnitUsageReportResponse'
            text/csv:
              schema:
                $ref: '#/components/schemas/UnitUsageReportResponse'
          description: ''
        '400':
          description: Invalid parameters
        '404':
          description: Billing information not found
      security:
        - api_key: []
        - oauth2: []
        - supabase_session: []
components:
  schemas:
    UnitUsageReportResponse:
      type: object
      properties:
        organization_id:
          type: integer
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        group_by:
          type: string
        timezone:
          type: string
          description: Timezone of the month boundaries (UTC).
        untyped_scheme:
          type: boolean
          description: >-
            True when the organization's charges in this range weren't recorded
            per unit; per-unit credit rows are then null and only counts and
            totals apply.
        old_text_pricing:
          type: boolean
          description: >-
            True when text simulations are billed at a flat rate, so
            `#Responses` is null.
        periods:
          type: array
          items:
            type: string
          description: Month keys (`YYYY-MM`) in order.
        rows:
          type: array
          items:
            $ref: '#/components/schemas/UnitUsageReportRow'
      required:
        - end_date
        - group_by
        - old_text_pricing
        - organization_id
        - periods
        - rows
        - start_date
        - timezone
        - untyped_scheme
    UnitUsageReportRow:
      type: object
      properties:
        key:
          type: string
          description: Stable row identifier, e.g. `voice_credits`.
        group:
          type: string
          description: Section, e.g. Simulations or Monitoring.
        unit:
          type: string
          description: Billable unit, e.g. Voice Simulations.
        field:
          type: string
          description: 'Measure, e.g. #Minutes or Credits.'
        kind:
          enum:
            - count
            - number
            - credits
          type: string
          description: |-
            * `count` - count
            * `number` - number
            * `credits` - credits
          x-spec-enum-id: 54fad001ba9172b8
        values:
          type: object
          additionalProperties:
            type:
              - number
              - 'null'
            format: double
          description: Value per month key; null when not recoverable.
        total:
          type:
            - number
            - 'null'
          format: double
      required:
        - field
        - group
        - key
        - kind
        - total
        - unit
        - values
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-CEKURA-API-KEY
      description: >-
        API Key Authentication. It should be included in the header of each
        request.
    oauth2:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth access token issued by Cekura for connected apps.
    supabase_session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Cekura dashboard session token. Not a customer API credential.

````