---
title: "GET /v1/public/stats/model-usage"
method: GET
path: "/v1/public/stats/model-usage"
tags: ["Stats"]
---

# GET /v1/public/stats/model-usage

`GET /v1/public/stats/model-usage`

Get model usage statistics for the AI Gateway.
Returns time series data and a leaderboard of top models by total tokens.

## Query parameters

- `timeframe` '24h' | '7d' | '30d' | '3m' | '1y'

## Response `200`

Ok

- union
  - ResultSuccessModelUsageResponse
    - `data` ModelUsageResponse, required
      - `timeSeries` ModelUsageTimeSeriesDataPoint[], required
        - `time` string, required
        - `models` ModelTokens[], required
          - `model` string, required
          - `totalTokens` number, double, required
      - `leaderboard` ModelUsageLeaderboardEntry[], required
        - `rank` number, double, required
        - `model` string, required
        - `author` string, required
        - `totalTokens` number, double, required
        - `percentChange` number, double, nullable, required
    - `error` null, nullable, required
  - ResultErrorString
    - `data` null, nullable, required
    - `error` string, required

## Changes

- **2025-12-18** `9888008a3ce5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/helicone/apis/helicone-api/changes/v1/public/stats/model-usage/get.md)

---

[API](https://skmtc.dev/helicone/apis/helicone-api.md) · [All operations](https://skmtc.dev/helicone/apis/helicone-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/helicone/helicone-api/revisions/dfd1a960c421/schema)