Clarity Processing Usage API

openapi: 3.2.0
info:
  title: Fast Processing Usage API
  version: 0.1.0
tags:
- name: processing-usage
paths:
  /api/v1/processing-usage:
    get:
      tags:
      - processing-usage
      summary: Get Processing Usage
      description: 'What processing cost the project per period.


        Args:

        start / end: inclusive days, counted in ``time_zone``; default the last 30 days.

        interval: period length. group_by: one dimension to split totals and periods by.

        origin / step / operator_id: narrow to rows of one origin, step or operator.


        Returns:

        Totals, totals per group, and per-period counters. ``cost_usd`` is set for staff

        (``users.is_admin``) and null for everyone else.


        Raises:

        HTTPException 422: unknown time zone, ``start`` after ``end``, or a range over

        ``MAX_RANGE_DAYS``.

        HTTPException 403 / 404: from the token/project resolution.'
      operationId: get_processing_usage_api_v1_processing_usage_get
      security:
      - HTTPBearer: []
      parameters:
      - name: start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: 'First day, inclusive. Default: 29 days before end'
          title: Start
        description: 'First day, inclusive. Default: 29 days before end'
      - name: end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: 'Last day, inclusive. Default: today in time_zone'
          title: End
        description: 'Last day, inclusive. Default: today in time_zone'
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - day
          - week
          - month
          type: string
          default: day
          title: Interval
      - name: time_zone
        in: query
        required: false
        schema:
          type: string
          description: IANA time zone the days are counted in
          default: UTC
          title: Time Zone
        description: IANA time zone the days are counted in
      - name: group_by
        in: query
        required: false
        schema:
          enum:
          - none
          - operator
          - model
          - origin
          - step
          type: string
          default: none
          title: Group By
      - name: origin
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - ingest
            - reprocess
            - classify
            - preview
            - unknown
            type: string
          - type: 'null'
          title: Origin
      - name: step
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Step
      - name: operator_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          title: Operator Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingUsageResponse'
        '403':
          description: The caller is not a member of the project
        '422':
          description: Unknown time zone, start after end, or a range over the limit
components:
  schemas:
    UsagePeriod:
      properties:
        runs:
          type: integer
          title: Runs
          default: 0
        tickets:
          type: integer
          title: Tickets
          default: 0
        calls:
          type: integer
          title: Calls
          default: 0
        input_tokens:
          type: integer
          title: Input Tokens
          default: 0
        cached_tokens:
          type: integer
          title: Cached Tokens
          default: 0
        output_tokens:
          type: integer
          title: Output Tokens
          default: 0
        cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost Usd
        period:
          type: string
          title: Period
          description: Start of the period, YYYY-MM-DD in the requested time zone
        groups:
          items:
            $ref: '#/components/schemas/UsageGroup'
          type: array
          title: Groups
      type: object
      required:
      - period
      title: UsagePeriod
    UsageCounters:
      properties:
        runs:
          type: integer
          title: Runs
          default: 0
        tickets:
          type: integer
          title: Tickets
          default: 0
        calls:
          type: integer
          title: Calls
          default: 0
        input_tokens:
          type: integer
          title: Input Tokens
          default: 0
        cached_tokens:
          type: integer
          title: Cached Tokens
          default: 0
        output_tokens:
          type: integer
          title: Output Tokens
          default: 0
        cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost Usd
      type: object
      title: UsageCounters
      description: 'What a slice of processing cost. ``runs`` is the billing unit: a ticket handed to a step

        or operator once in a request, however many LLM calls it took. ``tickets`` counts distinct

        tickets. ``cost_usd`` is our provider cost and is null unless the viewer is staff.'
    ProcessingUsageResponse:
      properties:
        project_id:
          type: integer
          title: Project Id
        start:
          type: string
          format: date
          title: Start
        end:
          type: string
          format: date
          title: End
        interval:
          type: string
          enum:
          - day
          - week
          - month
          title: Interval
        time_zone:
          type: string
          title: Time Zone
        group_by:
          type: string
          enum:
          - none
          - operator
          - model
          - origin
          - step
          title: Group By
        cost_visible:
          type: boolean
          title: Cost Visible
        totals:
          $ref: '#/components/schemas/UsageCounters'
        groups:
          items:
            $ref: '#/components/schemas/UsageGroup'
          type: array
          title: Groups
          description: Totals per group over the whole range
        periods:
          items:
            $ref: '#/components/schemas/UsagePeriod'
          type: array
          title: Periods
      type: object
      required:
      - project_id
      - start
      - end
      - interval
      - time_zone
      - group_by
      - cost_visible
      - totals
      - periods
      title: ProcessingUsageResponse
    UsageGroup:
      properties:
        runs:
          type: integer
          title: Runs
          default: 0
        tickets:
          type: integer
          title: Tickets
          default: 0
        calls:
          type: integer
          title: Calls
          default: 0
        input_tokens:
          type: integer
          title: Input Tokens
          default: 0
        cached_tokens:
          type: integer
          title: Cached Tokens
          default: 0
        output_tokens:
          type: integer
          title: Output Tokens
          default: 0
        cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost Usd
        key:
          type: string
          title: Key
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      type: object
      required:
      - key
      title: UsageGroup
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic