---
title: "Get Usage"
method: GET
path: "/usage"
tags: ["Billing"]
---

# Get Usage

`GET /usage`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/usage`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

## Query parameters

- `start` string, date-time, nullable: Window start (inclusive, ISO-8601); defaults to 7 days before `end`. Bounds job and sandbox creation time.
- `end` string, date-time, nullable: Window end (exclusive, ISO-8601); defaults to now. The window is capped at 90 days.
- `group_by` 'total' | 'day' | 'model'

## Response `200`

Successful Response

- UsageResponse
  - `start` string, date-time, required: Window start (inclusive).
  - `end` string, date-time, required: Window end (exclusive).
  - `group_by` 'total' | 'day' | 'model', required
  - `total_jobs` integer, required: Jobs submitted across the whole window, chat completions included.
  - `total_spent` number, required: Net amount spent across the whole window.
  - `currency` string, required: ISO-4217 currency code for every amount in this response.
  - `data` UsageBucket[]: One bucket per `group_by` group.
    - `key` string, required: What this bucket rolls up: `"total"`, an ISO date (`YYYY-MM-DD`, UTC), or a public model id, or `sandbox/<gpu_model>` for GPU sandboxes — per `group_by`.
    - `jobs` integer, required: Jobs submitted in this bucket, chat completions included.
    - `spent` number, required: Net amount spent in this bucket.

## Other responses

- `400`: Invalid or failed-validation request.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `403`: Insufficient scope or plan.
- `404`: Resource not found.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-10-16** `06692d16e78a`: 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)