---
title: "Spend, tokens, seconds and video counts between two UTC dates, by day, by model and resolution, and by key"
method: GET
path: "/v1/usage"
tags: ["platform-api"]
---

# Spend, tokens, seconds and video counts between two UTC dates, by day, by model and resolution, and by key

`GET /v1/usage`

## Request

- Base URL: `https://api.cuddler.ai`
- URL: `https://api.cuddler.ai/v1/usage`
- Auth: HTTP bearer

## Query parameters

- `from` string, required
- `to` string, required

## Response `200`

Usage between the two dates

- object
  - `object` 'usage', required
  - `from` string, required
  - `to` string, required
  - `total` object, required
    - `usd` string, required
    - `tokens` integer, required
    - `seconds` number, required
    - `videos_succeeded` integer, required
    - `videos_failed` integer, required
    - `images_succeeded` integer
    - `images_failed` integer
    - `music_succeeded` integer
    - `music_failed` integer
    - `speech_succeeded` integer
    - `speech_failed` integer
    - `speech_units` object
      - `character` integer
      - `utf8_byte` integer
      - `utf16_unit` integer
      - `audio_token` integer
      - `minimax_character` integer
  - `by_day` object[], required
    - `usd` string, required
    - `tokens` integer, required
    - `seconds` number, required
    - `videos_succeeded` integer, required
    - `videos_failed` integer, required
    - `images_succeeded` integer
    - `images_failed` integer
    - `music_succeeded` integer
    - `music_failed` integer
    - `speech_succeeded` integer
    - `speech_failed` integer
    - `speech_units` object
      - `character` integer
      - `utf8_byte` integer
      - `utf16_unit` integer
      - `audio_token` integer
      - `minimax_character` integer
    - `date` string, required
  - `by_model` object[], required
    - `usd` string, required
    - `tokens` integer, required
    - `seconds` number, required
    - `videos_succeeded` integer, required
    - `videos_failed` integer, required
    - `images_succeeded` integer
    - `images_failed` integer
    - `music_succeeded` integer
    - `music_failed` integer
    - `speech_succeeded` integer
    - `speech_failed` integer
    - `speech_units` object
      - `character` integer
      - `utf8_byte` integer
      - `utf16_unit` integer
      - `audio_token` integer
      - `minimax_character` integer
    - `model` union, required
      - 'seedance-2.5' | 'seedance-2.0' | 'seedance-2.0-mini' | 'minimax-h3' | 'wan-3.0' | 'wan-3.0-prime' | 'happyhorse-1.0' | 'happyhorse-1.1' | 'wan-2.6' | 'wan-2.7' | 'ltx-2.5' | 'minimax-hailuo-2.3' | 'pixverse-6' | 'grok-video-1.5' | 'kling-3.0' | 'kling-2.6' | 'kling-2.5-turbo' | 'kling-o1' | 'kling-o3' | 'vidu-q4-preview' | 'runway-gen4.5' | 'runway-gen4-turbo' | 'veo-3.1' | 'veo-3.1-fast' | 'veo-3.1-lite' | 'veo-3' | 'veo-3-fast' | 'veo-2' | 'gemini-omni-flash' | 'seedream-5' | 'seedream-5-pro' | 'qwen-image-3' | 'z-image-turbo' | 'grok-imagine-2.0' | 'ideogram-4' | 'ideogram-4.5' | 'recraft-4.1' | 'nano-banana-2.1' | 'nano-banana-2' | 'nano-banana-2-lite' | 'nano-banana-pro' | 'imagen-4-ultra' | 'imagen-4' | 'imagen-4-fast' | 'imagen-3' | 'imagen-3-fast' | 'gpt-image-2.5-sunburst' | 'gpt-image-2.5-flare' | 'gpt-image-2' | 'gpt-image-1.5' | 'gpt-image-1-mini' | 'gpt-image-1'
      - 'elevenlabs-v4' | 'elevenlabs-v4-turbo' | 'elevenlabs-flash-v2.5' | 'fish-s2.1-pro' | 'gemini-3.8-flash-tts' | 'gemini-3.8-flash-lite-tts' | 'minimax-speech-2.8-hd' | 'minimax-speech-2.8-turbo'
      - 'lyria-3-pro' | 'lyria-3' | 'lyria-2' | 'eleven-music-2.5'
    - `resolution` union, required
      - '360p' | '480p' | '540p' | '720p' | '768p' | '1080p' | '1440p' | '0.5K' | '1K' | '2K' | '4K'
      - 'audio'
  - `by_key` object[], required
    - `usd` string, required
    - `tokens` integer, required
    - `seconds` number, required
    - `videos_succeeded` integer, required
    - `videos_failed` integer, required
    - `images_succeeded` integer
    - `images_failed` integer
    - `music_succeeded` integer
    - `music_failed` integer
    - `speech_succeeded` integer
    - `speech_failed` integer
    - `speech_units` object
      - `character` integer
      - `utf8_byte` integer
      - `utf16_unit` integer
      - `audio_token` integer
      - `minimax_character` integer
    - `api_key_id` string, required
    - `api_key_name` string, required

## Other responses

- `400`: invalid_request — not calendar dates, to before from, or more than 366 days
- `401`: unauthorized — no key, or an unknown or revoked one (WWW-Authenticate: Bearer)
- `403`: organization_suspended — the organization is not active; forbidden — a test key on a live-only route
- `404`: not_found — the Platform API is switched off, or the object does not exist
- `429`: rate_limited — over this key's requests per minute (Retry-After)
- `500`: internal_error — quote request_id when contacting support

---

[API](https://skmtc.dev/cuddler/apis/cuddler-platform-api.md) · [All operations](https://skmtc.dev/cuddler/apis/cuddler-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cuddler/apis/cuddler-platform-api/revisions/f03943ceadff?raw)