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

# Usage & Cost

Retrieve your workspace's usage and cost for a time window — the same per-request-type breakdown shown in the dashboard, available with your API key. Use it to reconcile billing or power an internal usage dashboard.

Usage is aggregated across every Environment in the workspace; it is not scoped to a single Environment or API key.

## Choosing a Window

Set the window with a `period` (trailing days, `1`–`365`, default `30`) **or** an explicit `from`/`to` range — never both. `from` and `to` are inclusive, must be sent together with `from` no later than `to` or today, and can span at most 365 days. Set them to the same day to read a single day's usage.

## Cost

Each request type returns a `count` and a `cost_micros`.

> [!NOTE]
>
> Costs are integers in **micro-USD** — millionths of one US dollar — so amounts stay exact. Divide by 1,000,000 to convert to dollars: `250000` is `$0.25`. Each category's `cost_micros` is its `count` times your workspace's configured price for that category; unpriced categories (including `video` and `website` artifacts) return a `0` cost.

## Next Steps

> **[Check One Event](/latest/events/check-event)**
>
> Submit Events that this usage counts.

> **[Policies](/latest/first-steps/policies)**
>
> See how each checked Event maps to a request type.


## OpenAPI

````yaml GET /api/usage
openapi: 3.1.0
info:
  title: WhiteCircle API Backend
  description: 'Authentication: Bearer API Key Required'
  license:
    name: ''
  version: '2026-06-01'
servers:
  - url: https://eu.whitecircle.com
  - url: https://us.whitecircle.com
security: []
tags:
  - name: Session
    description: Session-based content checking and moderation
  - name: User
    description: User risk assessment and scoring
  - name: Policy
    description: Policy management CRUD
  - name: Metric
    description: Metric management CRUD
  - name: Artifact
    description: Standalone artifact moderation
  - name: Events
    description: Append-only event ingestion and public event lookup
  - name: Condition
    description: Metadata-driven policy routing
  - name: Billing
    description: Usage and cost reporting
paths:
  /api/usage:
    get:
      tags:
        - Billing
      operationId: usage_v1
      parameters:
        - name: whitecircle-version
          in: header
          description: API Version
          required: true
          schema:
            type: string
          example: '2026-06-01'
        - name: period
          in: query
          description: >-
            Trailing window in days (1–365). Mutually exclusive with
            `from`/`to`. Defaults to 30.
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int32
            minimum: 1
            maximum: 365
        - name: from
          in: query
          description: >-
            Inclusive start day (YYYY-MM-DD). Requires `to`. Mutually exclusive
            with `period`.
          required: false
          schema:
            type:
              - string
              - 'null'
            format: date
        - name: to
          in: query
          description: >-
            Inclusive end day (YYYY-MM-DD). Requires `from`. Mutually exclusive
            with `period`.
          required: false
          schema:
            type:
              - string
              - 'null'
            format: date
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReport'
              example:
                from: '2026-05-03'
                to: '2026-06-01'
                message:
                  count: 1280
                  cost_micros: 12800
                artifact:
                  image:
                    count: 340
                    cost_micros: 34000
                  video:
                    count: 12
                    cost_micros: 0
                  website:
                    count: 5
                    cost_micros: 0
                tool:
                  count: 210
                  cost_micros: 2100
                agent:
                  count: 64
                  cost_micros: 1280
                function:
                  count: 88
                  cost_micros: 880
                reasoning:
                  count: 41
                  cost_micros: 410
                total_micros: 51470
        '400':
          description: Bad Request
      security:
        - bearerAuth: []
components:
  schemas:
    UsageReport:
      type: object
      required:
        - from
        - to
        - message
        - artifact
        - tool
        - agent
        - function
        - reasoning
        - total_micros
      properties:
        from:
          type: string
          format: date
          description: Inclusive first day covered (YYYY-MM-DD).
        to:
          type: string
          format: date
          description: Inclusive last day covered (YYYY-MM-DD).
        message:
          $ref: '#/components/schemas/UsageAmount'
        artifact:
          $ref: '#/components/schemas/ArtifactAmount'
        tool:
          $ref: '#/components/schemas/UsageAmount'
        agent:
          $ref: '#/components/schemas/UsageAmount'
        function:
          $ref: '#/components/schemas/UsageAmount'
        reasoning:
          $ref: '#/components/schemas/UsageAmount'
        total_micros:
          type: integer
          format: int64
          description: Total cost across all categories, in millionths of one USD.
    UsageAmount:
      type: object
      required:
        - count
        - cost_micros
      properties:
        count:
          type: integer
          format: int64
          description: Number of checks in this category.
          minimum: 0
        cost_micros:
          type: integer
          format: int64
          description: Cost in millionths of one USD (divide by 1,000,000 for dollars).
    ArtifactAmount:
      type: object
      required:
        - image
        - video
        - website
      properties:
        image:
          $ref: '#/components/schemas/UsageAmount'
        video:
          $ref: '#/components/schemas/UsageAmount'
          description: Video artifact checks are counted but not billed.
        website:
          $ref: '#/components/schemas/UsageAmount'
          description: Website artifact checks are counted but not billed.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key required. Format: Bearer wc-your-api-key'

````

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