---
title: "Detailed Usage Query"
method: POST
path: "/v1/admin/usage/query"
tags: ["beta.admin.billing"]
---

# Detailed Usage Query

`POST /v1/admin/usage/query`

## Request

- Base URL: `https://api.mistral.ai`
- URL: `https://api.mistral.ai/v1/admin/usage/query`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mistral/apis/mistral-ai-api/docs/v1/admin/usage/query/post.ts> (a function with typed inputs; its response is checked against the schema)

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`.

## Request body

- UsageQueryIN
  - `usage_type` UsageType[], nullable: Usage event types to include.
  - `billing_metric` string[], nullable: Billing metric identifiers to include.
  - `billing_display_name` string[], nullable: Customer-facing billing metric names to include.
  - `billing_group` string[], nullable: Billing metric components to include.
  - `workspace_ids` string[], nullable: Workspace IDs to include. Use null to include usage without a workspace.
  - `organization_id` string[], nullable: Organization IDs to include within the authenticated customer.
  - `user_id` string[], nullable: User IDs to include.
  - `service_account_id` string[], nullable: Service account IDs to include.
  - `api_key_id` string[], nullable: API key IDs to include.
  - `api_zone` string[], nullable: Inference regions to include.
  - `service_tier` string[], nullable: Service tiers to include.
  - `start` string, date-time, required: Inclusive start of the usage interval.
  - `end` string, date-time, required: Exclusive end of the usage interval.
  - `filters` AdminUsageQueryFilter[], nullable: Additional inclusion or exclusion filters applied alongside the dimension fields.
    - `field` 'usage_type' | 'billing_metric' | 'billing_display_name' | 'billing_group' | 'workspace_id' | 'organization_id' | 'user_id' | 'service_account_id' | 'api_key_id' | 'api_zone' | 'service_tier', required: Usage dimension to filter.
    - `operator` 'is' | 'is_not', required: Whether rows must match or must not match the supplied values.
    - `values` string[], required: Accepted or excluded values. Use null to filter missing dimension values.
  - `group_by` string[], 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.
  - `untracked` boolean, nullable: Filter by attribution status. Omit or use null to include both tracked and untracked usage.
  - `limit` integer, nullable: Maximum number of grouped rows to return.
  - `offset` integer, nullable: Number of grouped rows to skip.
  - `include_aggregates` boolean: Return aggregates computed over the complete filtered result set.
  - `include_nb_api_calls` boolean: Include the number of distinct API calls in grouped rows and aggregates.

## Response `200`

Successful Response

- UsageQueryOUT
  - `groups` UsageQueryRowOUT[], required: Grouped usage rows.
    - `customer_id` string, nullable: Customer ID for this row.
    - `usage_type` string, nullable: Usage event type.
    - `billing_metric` string, nullable: Billing metric identifier.
    - `billing_group` string, nullable: Billing metric component.
    - `workspace_id` string, nullable: Workspace ID.
    - `organization_id` string, nullable: Organization ID.
    - `user_id` string, nullable: User ID.
    - `service_account_id` string, nullable: Service account ID.
    - `api_key_id` string, nullable: API key ID.
    - `api_zone` string, nullable: Inference region.
    - `service_tier` string, nullable: Service tier.
    - `timestamp` string, date-time, nullable: Timestamp of an unbucketed usage row, expressed using the request start timestamp's UTC offset.
    - `time_bucket` string, date-time, nullable: Start of the UTC time bucket, expressed using the request start timestamp's UTC offset.
    - `value` integer, nullable: Total usage value for this row.
    - `count` integer, nullable: Number of usage records in this row.
    - `nb_api_calls` integer, nullable: Number of distinct API calls.
    - `billing_display_name` string, nullable: Customer-facing billing metric name.
    - `customer_tier` string, nullable: Customer tier.
    - `untracked` boolean, nullable: Whether attribution was unavailable.
    - `call_source` string, nullable: Product source of the call.
    - `call_type` string, nullable: Type of call within its source.
  - `aggregates` UsageQueryAggregatesOUT
    - `total_value` number, required: Total usage value across all matching rows.
    - `total_count` integer, required: Total number of matching usage records.
    - `total_api_calls` integer, required: Total number of distinct API calls.
    - `customer_count` integer, required: Number of matching customers.
    - `usage_type_count` integer, required: Number of matching usage types.
  - `metadata` UsageQueryMetadataOUT, required
    - `query_params` UsageQueryParamsOUT, required
      - `usage_type` UsageType[], nullable: Usage event types to include.
      - `billing_metric` string[], nullable: Billing metric identifiers to include.
      - `billing_display_name` string[], nullable: Customer-facing billing metric names to include.
      - `billing_group` string[], nullable: Billing metric components to include.
      - `workspace_ids` string[], nullable: Workspace IDs to include. Use null to include usage without a workspace.
      - `organization_id` string[], nullable: Organization IDs to include within the authenticated customer.
      - `user_id` string[], nullable: User IDs to include.
      - `service_account_id` string[], nullable: Service account IDs to include.
      - `api_key_id` string[], nullable: API key IDs to include.
      - `api_zone` string[], nullable: Inference regions to include.
      - `service_tier` string[], nullable: Service tiers to include.
      - `start` string, date-time, required: Inclusive start of the queried interval.
      - `end` string, date-time, required: Exclusive end of the queried interval.
      - `customer_id` string, nullable: Customer scope derived from the authenticated Admin API key.
      - `filters` AdminUsageQueryFilter[], nullable: Additional inclusion or exclusion filters applied to the query.
        - `field` 'usage_type' | 'billing_metric' | 'billing_display_name' | 'billing_group' | 'workspace_id' | 'organization_id' | 'user_id' | 'service_account_id' | 'api_key_id' | 'api_zone' | 'service_tier', required: Usage dimension to filter.
        - `operator` 'is' | 'is_not', required: Whether rows must match or must not match the supplied values.
        - `values` string[], required: Accepted or excluded values. Use null to filter missing dimension values.
      - `group_by` string[], 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.
      - `limit` integer, nullable: Applied row limit.
      - `offset` integer, nullable: Applied row offset.
      - `untracked` boolean, nullable: Applied attribution filter.
      - `include_nb_api_calls` boolean: Whether distinct API-call counts were requested.
    - `has_more` boolean, required: Whether another page of grouped rows is available.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-15** `f42449e21ee5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mistral/apis/mistral-ai-api/changes/v1/admin/usage/query/post.md)

---

[API](https://skmtc.dev/mistral/apis/mistral-ai-api.md) - [All operations](https://skmtc.dev/mistral/apis/mistral-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mistral/apis/mistral-ai-api/revisions/08a585fb75bc?raw)