---
title: "Usage over a window, grouped"
method: GET
path: "/api/v1/usage"
tags: ["Usage"]
---

# Usage over a window, grouped

`GET /api/v1/usage`

## Request

- Base URL: `https://api.imagestep.dev`
- URL: `https://api.imagestep.dev/api/v1/usage`
- Auth: API key in header `Authorization`

What was spent over a time window, grouped by atomic op, by API key, or by UTC day, with the
window's `total` beside the groups:

- `jobs` — jobs created in the window
- `credits` and `items` — what those jobs were charged and how many of their items settled, so far
- `sync` — synchronous calls (`/images/transform`, `/images/render`) that succeeded and so cost an op from the allowance; never counted in `jobs`. `/images/metadata` is free and not counted

A job submitted as a raw `type` groups under that type; a console session, which has no key, groups
under `console`. Days are UTC. Usage lives as long as the job records it comes from, so a window
older than the plan's retention reads short.

USE THIS WHEN:
- An agent has a budget and needs to know what it has spent, and on what
- Attributing cost across several keys (one key per agent is the usual shape)

DO NOT USE WHEN:
- You need one job's own cost → `GET /api/v1/jobs/{id}` (`actualCredits`, and `credits` per item)
- You need every credit movement, top-ups and refunds included → the credit ledger, which a signed-in console session reads and an API key cannot

## Query parameters

- `from` string
- `to` string
- `groupBy` 'op' | 'key' | 'day'

## Response `200`

The window, its total and its groups

## Other responses

- `400`: - `invalid_param` on `groupBy` — not `op`, `key` or `day` - `invalid_param` on `from` / `to` — neither `YYYY-MM-DD` nor an ISO-8601 instant - `invalid_param` on `from` — not before `to`, or the window spans more than 366 days
- `429`: Rate limited — `error.code` is `rate_limited` and `retryable` is true. `Retry-After` says how many seconds to wait.

---

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