---
title: "Get Usage Stats"
method: GET
path: "/api/usage/stats"
tags: ["Usage"]
---

# Get Usage Stats

`GET /api/usage/stats`

Get comprehensive usage statistics with time series.

## Query parameters

- `period` 'last_day' | 'last_week' | 'last_month' | 'last_3_months' | 'last_6_months' | 'last_90_days' | 'last_year' | 'current_month' | 'custom' — Time period: last_day, last_week, last_month, last_3_months, last_6_months, last_90_days, last_year, current_month, custom
- `start_date` string, nullable — Start date for custom period (YYYY-MM-DD)
- `end_date` string, nullable — End date for custom period (YYYY-MM-DD)
- `group_by` 'hour' | 'day' — Group by: hour or day
- `api_key_id` string, nullable — Filter by specific API key ID
- `model` string, nullable — Filter by specific model
- `include_per_key` boolean — When true (and no api_key_id filter), include per-key breakdown in one response.
- `skip_cache` boolean — Force-drain the Redis usage stream so pending events land in usage_logs before reading. Use when the user clicks refresh.

## Response `200`

Successful Response

- UsageStatsResponse
  - `success` boolean
  - `message` string, nullable
  - `data` UsageStatsResult
    - `period` string, required — Time period (last_day, last_week, etc.)
    - `period_start` string, required — Start of period (ISO)
    - `period_end` string, required — End of period (ISO)
    - `group_by` string, required — Grouping: hour or day
    - `time_series` TimeSeriesDataPoint[] — Time series data points
      - `timestamp` string, required — ISO timestamp
      - `requests` integer — Number of requests
      - `input_tokens` integer — Original input tokens
      - `compressed_input_tokens` integer — Compressed input tokens
      - `output_tokens` integer — Output tokens
      - `cost_usd` number — Cost in USD
      - `savings_usd` number — Savings in USD
    - `total_requests` integer — Total number of requests
    - `total_input_tokens` integer — Total original input tokens
    - `total_compressed_input_tokens` integer — Total compressed input tokens
    - `total_output_tokens` integer — Total output tokens
    - `total_cost_usd` number — Total cost in USD
    - `total_savings_usd` number — Total savings in USD
    - `total_spent_usd` number — Total amount spent in USD
    - `api_key_id` string, nullable — Filtered by API key ID
    - `model` string, nullable — Filtered by model
    - `per_key_time_series` object, nullable — Per-API-key time series, keyed by api_token_id. Set when include_per_key=true.

## Other responses

- `400` — Bad Request
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/compresr/apis/compresr-platform-api.md) · [All operations](https://skmtc.net/compresr/apis/compresr-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/compresr/compresr-platform-api/revisions/93ee959dfa51/schema)