---
title: "Get Inference Usage Aggregate"
method: GET
path: "/v2/usage/inference"
tags: ["usage"]
---

# Get Inference Usage Aggregate

`GET /v2/usage/inference`

Aggregate the team's inference usage into time buckets, optionally grouped.

## Query parameters

- `start` string, date-time, nullable — Window start; defaults to end-7d
- `end` string, date-time, nullable — Window end; defaults to now
- `bucket_width` '1h' | '1d'
- `group_by` 'api_key' | 'byok' | 'model' | 'user' | 'route', nullable
- `user_id` string, uuid, nullable
- `api_key_id` string, uuid, nullable
- `byok_credential_id` string, uuid, nullable

## Response `200`

Successful Response

- InferenceUsageAggregateResponse
  - `start` string, date-time, required
  - `end` string, date-time, required
  - `bucket_width` '1h' | '1d', required
  - `group_by` 'api_key' | 'byok' | 'model' | 'user' | 'route', nullable
  - `total_requests` integer, required
  - `total_cost` number, required
  - `buckets` InferenceUsageBucket[], required
    - `start` string, date-time, required
    - `groups` InferenceUsageGroup[], required
      - `api_key_id` string, uuid, nullable
      - `api_key_name` string, nullable
      - `api_key_is_default` boolean
      - `api_key_owner` string, nullable
      - `byok` boolean
      - `byok_credential_id` string, uuid, nullable
      - `byok_name` string, nullable
      - `byok_scope` 'member' | 'team', nullable
      - `byok_owner` string, nullable
      - `model` string, nullable
      - `user_id` string, uuid, nullable
      - `user_name` string, nullable
      - `route` string, nullable
      - `requests` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `cached_input_tokens` integer, required
      - `cost` number, required

## Other responses

- `400` — Invalid or malformed request
- `401` — Missing or invalid credentials
- `403` — Caller may not access this resource
- `404` — Referenced entity does not exist
- `409` — Resource already exists
- `422` — Validation Error

---

[API](https://skmtc.dev/hud/apis/hud-platform.md) · [All operations](https://skmtc.dev/hud/apis/hud-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hud/hud-platform/revisions/58558fc733d9/schema)