---
title: "Usage of this key (or the whole account) over a window"
method: GET
path: "/api/v1/usage"
tags: ["Public API v1"]
---

# Usage of this key (or the whole account) over a window

`GET /api/v1/usage`

## Request

- Base URL: `https://api.vieneu.io`
- URL: `https://api.vieneu.io/api/v1/usage`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Totals by outcome, tokens, characters, seconds of audio and generation time, broken down per day, per route, per voice and per error code — from the per-call ledger every `/v1` call is recorded in. `POST /v1/tts` rows start `queued` and close as `ok`/`error` when the job finishes; `cache_hit` is a request served from the content cache. `tokenCost` is what was deducted before the call ran. Calls refused by the rate limiter never reach the ledger. Window capped at 92 days; default the last 30.

## Query parameters

- `from` string
- `to` string
- `scope` 'key' | 'account'

## Response `200`

The summary for the window.

- PublicUsageResponseDto
  - `scope` 'key' | 'account', required
  - `apiKeyId` string, nullable: The key summarised (`scope=key`).
  - `userId` string, nullable: The account summarised (`scope=account`).
  - `from` string, required
  - `to` string, required
  - `totals` UsageTotalsDto, required
    - `requests` number, required: Calls that reached a handler in the window (every outcome).
    - `ok` number, required: Delivered audio (sync routes) or finished jobs (`POST /v1/tts`).
    - `queued` number, required: `POST /v1/tts` jobs still in the queue at the time of the query.
    - `cacheHit` number, required: Served from the content cache — billed, no generation.
    - `denied` number, required: Refused with a 4xx (bad voice, quota, moderation…). Not billed.
    - `error` number, required: Failed with a 5xx or truncated mid-stream. Refunded.
    - `tokenCost` number, required: Tokens deducted (before refunds — see `refunded` on events).
    - `characters` number, required: Characters submitted (the billed quantity).
    - `audioSeconds` number, required: Seconds of audio produced.
    - `avgGenMs` number, nullable: Mean worker time per successful call, ms.
    - `p95GenMs` number, nullable: 95th percentile of the same, ms.
  - `byDay` UsageByDayDto[], required
    - `day` string, required
    - `requests` number, required
    - `ok` number, required
    - `denied` number, required
    - `error` number, required
    - `tokenCost` number, required
    - `characters` number, required
    - `audioSeconds` number, required
    - `avgGenMs` number, nullable
  - `byRoute` UsageByRouteDto[], required
    - `route` string, required: Logical route: `tts`, `tts_stream`, `audio_speech`, `vapi_speech`, `clone`, `dialogue`, `dub`, `srt`, `upload`, `prepare`, `voices_create`, `voices_delete`.
    - `requests` number, required
    - `ok` number, required
    - `denied` number, required
    - `error` number, required
    - `tokenCost` number, required
    - `avgGenMs` number, nullable
  - `byVoice` UsageByVoiceDto[], required: Top 100 by request count.
    - `voice` string, required: Voice id for catalogue/cloned voices; for one-shot cloning, the reference clip handle (basename of the uploaded file).
    - `voiceName` string, nullable
    - `engine` string, nullable
    - `requests` number, required
    - `tokenCost` number, required
    - `audioSeconds` number, required
    - `avgGenMs` number, nullable
    - `errors` number, required
  - `byErrorCode` UsageByErrorCodeDto[], required
    - `errorCode` string, required: Same vocabulary as the webhook `error.code`; 4xx refusals appear as `http_<status>`.
    - `statusCode` number, required
    - `count` number, required
    - `lastAt` string, required

## Other responses

- `400`: Unparseable date, or a scope other than key/account.
- `401`: API key missing, malformed, or revoked.

## Changes

- **2026-09-16** `98838c7c0e72`: 2 info
  - added the optional property `retryAfterSeconds` to the response with the `400` status
  - added the optional property `retryAfterSeconds` to the response with the `401` status
- **2026-09-14** `7a8e8de08984`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vieneu/apis/vieneu-api/changes/api/v1/usage/get.md)

---

[API](https://skmtc.dev/vieneu/apis/vieneu-api.md) - [All operations](https://skmtc.dev/vieneu/apis/vieneu-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vieneu/apis/vieneu-api/revisions/9518b716e16d?raw)