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

# Get organization AI inference usage costs

> **Disclaimer:** This beta endpoint is evolving; the API contract may change. <br /><br /> Returns a grand total and a list of daily AI inference usage cost records for the organization in the queried time period (maximum 31 days). There is one record per day, provider and model. Each record lists the tokens used, the average price and the cost for each metric, such as input, output, cache read and each cache write duration. All costs are at list price. All days in both the request and the response are evaluated based on the UTC timezone.

Beta

**Disclaimer:** This beta endpoint is evolving; the API contract may change. \
\
&#x20;Returns a grand total and a list of daily AI inference usage cost records for the organization in the queried time period (maximum 31 days). There is one record per day, provider and model. Each record lists the tokens used, the average price and the cost for each metric, such as input, output, cache read and each cache write duration. All costs are at list price. All days in both the request and the response are evaluated based on the UTC timezone.

#### Permission

The API key must have the `control-plane:organization:view-billing` permission.


## OpenAPI

````yaml _specs/cloud-openapi.json GET /v1/organizations/{organizationId}/inferenceUsageCost
openapi: 3.1.1
info:
  title: OpenAPI spec for ClickHouse Cloud
  version: '1.0'
  contact:
    name: ClickHouse Support
    url: >-
      https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1513344
    email: support@clickhouse.com
servers:
  - url: https://api.clickhouse.cloud
security:
  - basicAuth: []
tags:
  - name: Organization
  - name: Notifications
  - name: User management
  - name: Billing
  - name: Role Management
  - name: Service
  - name: Backup
  - name: Snapshot
  - name: API keys
  - name: Prometheus
  - name: ClickPipes
  - name: ClickStack
  - name: Postgres
  - name: UDF
  - name: Query API endpoints
  - name: Saved queries
paths:
  /v1/organizations/{organizationId}/inferenceUsageCost:
    get:
      tags:
        - Billing
      summary: Get organization AI inference usage costs
      description: >-
        **Disclaimer:** This beta endpoint is evolving; the API contract may
        change. <br /><br /> Returns a grand total and a list of daily AI
        inference usage cost records for the organization in the queried time
        period (maximum 31 days). There is one record per day, provider and
        model. Each record lists the tokens used, the average price and the cost
        for each metric, such as input, output, cache read and each cache write
        duration. All costs are at list price. All days in both the request and
        the response are evaluated based on the UTC timezone.
      operationId: inferenceUsageCostGet
      parameters:
        - in: path
          name: organizationId
          description: ID of the requested organization.
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: from_date
          description: Start date for the report, e.g. 2024-12-19.
          schema:
            type: string
            format: date
          required: true
        - in: query
          name: to_date
          description: >-
            End date (inclusive) for the report, e.g. 2024-12-20. This date
            cannot be more than 30 days after from_date (for a maximum queried
            period of 31 days).
          schema:
            type: string
            format: date
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    $ref: '#/components/schemas/InferenceUsageCost'
        '400':
          description: >-
            The request cannot be processed due to a client error. Please verify
            your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: >-
            An internal server error has occurred. If this issue persists,
            please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
components:
  schemas:
    InferenceUsageCost:
      properties:
        grandTotalCHC:
          description: Grand total cost of AI inference usage in ClickHouse Credits (CHCs).
          type: number
        costs:
          type: array
          description: >-
            List of AI inference usage cost records, one per day, provider and
            model. Empty when the organization has no usage.
          items:
            $ref: '#/components/schemas/InferenceUsageCostRecord'
    InferenceUsageCostRecord:
      properties:
        date:
          description: Date of the usage. ISO-8601 date, based on the UTC timezone.
          type: string
          format: date
          example: '2026-10-01'
        provider:
          description: Provider of the model.
          type: string
          example: anthropic
        model:
          description: >-
            ID of the model. This is the raw model ID; `modelName` has the
            display name.
          type: string
          example: claude-opus-4-8
        modelName:
          description: >-
            Display name of the model, as the usage page and the usage statement
            CSV show it.
          type: string
          example: Claude Opus 4.8
        metrics:
          type: array
          description: >-
            Usage and cost for each metric that has usage. The costs add up to
            `totalCHC`.
          items:
            $ref: '#/components/schemas/InferenceUsageCostMetric'
        totalCHC:
          description: >-
            Total cost of usage in ClickHouse Credits (CHCs) for this model on
            this date.
          type: number
        locked:
          description: >-
            When true, the record is immutable. Unlocked records are subject to
            change until locked.
          type: boolean
    InferenceUsageCostMetric:
      properties:
        metric:
          description: >-
            Name of the metric: `input`, `output`, `cache_read`,
            `cache_write_5m`, `cache_write_30m` or `cache_write_1h`. New values
            can appear.
          type: string
          example: cache_write_5m
        tokensMillions:
          description: >-
            Number of tokens used, in millions. For example, 1.5 means 1,500,000
            tokens.
          type: number
        pricePerMillionTokensCHC:
          description: >-
            Average price per million tokens in ClickHouse Credits (CHCs):
            `totalCHC` divided by `tokensMillions`. It is an average because one
            model can have more than one price. Zero when no tokens were used.
          type: number
        totalCHC:
          description: Cost of the tokens used in ClickHouse Credits (CHCs).
          type: number
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use key ID and key secret obtained in ClickHouse Cloud console:
        https://clickhouse.com/docs/cloud/manage/openapi
      x-permission-scopes: >-
        The scope list of a `security` requirement holds ClickHouse Cloud API
        key permission ids (for example `control-plane:organization:view`), not
        OAuth scopes. OpenAPI has no field for API key permissions, so this is
        the closest available place. A key must hold every permission listed on
        an operation to call it; an operation with no scopes needs none beyond a
        valid key. Every operation declares at most one requirement object,
        always for this scheme, so the list is only ever conjunctive —
        alternative sets of permissions are never expressed.

````