MImistral
beta.admin.billing

Detailed Usage Query

Changed on

Query the organization's detailed usage for a required time range.

Optional filters, caller-selected grouping and time buckets, pagination, aggregates, and distinct API-call counts are supported. The response contains usage quantities only; it does not include prices, currency, or calculated costs. For a fixed monthly report with pricing, use GET /v1/admin/usage.

post/v1/admin/usage/query

Request

Request body

usage_typeUsageType[] nullable

Usage event types to include.

billing_metricstring[] nullable

Billing metric identifiers to include.

billing_display_namestring[] nullable

Customer-facing billing metric names to include.

billing_groupstring[] nullable

Billing metric components to include.

workspace_idsstring[] nullable

Workspace IDs to include. Use null to include usage without a workspace.

organization_idstring[] nullable

Organization IDs to include within the authenticated customer.

user_idstring[] nullable

User IDs to include.

service_account_idstring[] nullable

Service account IDs to include.

api_key_idstring[] nullable

API key IDs to include.

api_zonestring[] nullable

Inference regions to include.

service_tierstring[] nullable

Service tiers to include.

startstring date-time required

Inclusive start of the usage interval.

endstring date-time required

Exclusive end of the usage interval.

group_bystring[] nullable

Dimensions used to group the returned usage rows.

time_bucket'second' | '1min' | '5min' | '15min' | '30min' | 'hour' | '4hours' | 'day' | 'week' | 'month' nullable

Time interval used to bucket grouped rows.

untrackedboolean nullable

Filter by attribution status. Omit or use null to include both tracked and untracked usage.

limitinteger nullable

Maximum number of grouped rows to return.

offsetinteger nullable

Number of grouped rows to skip.

include_aggregatesboolean

Return aggregates computed over the complete filtered result set.

include_nb_api_callsboolean

Include the number of distinct API calls in grouped rows and aggregates.

Example request

{
  "usage_type": [
    "usage",
    "ocr"
  ],
  "billing_metric": [
    "mistral-large"
  ],
  "billing_display_name": [
    "mistral-large-latest"
  ],
  "billing_group": [
    "input",
    "output"
  ],
  "workspace_ids": [
    "8b1f9229-42c0-4511-9d54-5f860f04d17a",
    null
  ],
  "organization_id": [
    "82e9b991-90ed-4c5f-b8b4-b69141d41c84"
  ],
  "user_id": [
    "7f8c8b54-bf28-470e-97ef-18d40d37e537"
  ],
  "service_account_id": [
    "3d77300f-67db-498b-98d2-e751635b4fcb"
  ],
  "api_key_id": [
    "b40f2e87-24f1-42ed-b196-f5e79203f989"
  ],
  "api_zone": [
    "us",
    "eu"
  ],
  "service_tier": [
    "standard",
    "priority"
  ],
  "start": "2026-08-01T00:00:00Z",
  "end": "2026-09-01T00:00:00Z",
  "filters": [
    {
      "field": "billing_display_name",
      "operator": "is_not",
      "values": [
        "mistral-small-latest"
      ]
    }
  ],
  "group_by": [
    "usage_type",
    "billing_metric",
    "billing_group"
  ],
  "time_bucket": "day",
  "limit": 1000,
  "include_aggregates": true,
  "include_nb_api_calls": true
}

Response

Successful Response

Example response

{
  "groups": [],
  "aggregates": {
    "total_value": 1500,
    "total_count": 12,
    "total_api_calls": 10,
    "customer_count": 1,
    "usage_type_count": 2
  },
  "metadata": {
    "query_params": {
      "usage_type": [
        "usage",
        "ocr"
      ],
      "billing_metric": [
        "mistral-large"
      ],
      "billing_display_name": [
        "mistral-large-latest"
      ],
      "billing_group": [
        "input",
        "output"
      ],
      "workspace_ids": [
        "8b1f9229-42c0-4511-9d54-5f860f04d17a",
        null
      ],
      "organization_id": [
        "82e9b991-90ed-4c5f-b8b4-b69141d41c84"
      ],
      "user_id": [
        "7f8c8b54-bf28-470e-97ef-18d40d37e537"
      ],
      "service_account_id": [
        "3d77300f-67db-498b-98d2-e751635b4fcb"
      ],
      "api_key_id": [
        "b40f2e87-24f1-42ed-b196-f5e79203f989"
      ],
      "api_zone": [
        "us",
        "eu"
      ],
      "service_tier": [
        "standard",
        "priority"
      ],
      "start": "2026-08-01T00:00:00Z",
      "end": "2026-09-01T00:00:00Z",
      "customer_id": "69bc23d6-4db3-47ad-9cce-bda1b24509f2",
      "filters": [
        {
          "field": "billing_metric",
          "operator": "is",
          "values": [
            "mistral-large"
          ]
        }
      ],
      "group_by": [
        "usage_type",
        "billing_metric"
      ],
      "time_bucket": "day",
      "limit": 1000,
      "include_nb_api_calls": true
    }
  }
}

Changes