---
title: Usage
url: https://base_url.placeholder/docs/api/usage
group: Surfaces
---

# Usage

What this account spent over a window — credits, jobs, items and synchronous calls — grouped by op, API key or day: the number an agent holds a budget against

1 endpoint under `/api/v1/usage`. What every call shares is on [the REST overview](https://base_url.placeholder/docs/api#conventions), and what they are for — with the calls for every SDK, the CLI and MCP — on [Jobs → What you are charged](https://base_url.placeholder/docs/jobs#settlement). `*` marks a required field.

- GET /api/v1/usage — Usage over a window, grouped

## Usage over a window, grouped

GET /api/v1/usage

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

### Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| from | query | string | Start of the window, inclusive. `YYYY-MM-DD` (UTC midnight) or an ISO-8601 instant. Defaults to 30 days before `to`; the window may span at most 366 days. |
| to | query | string | End of the window, exclusive — `2026-10-01` ends with the last instant of 30 September. Same formats. Defaults to now. |
| groupBy | query | string | What a group is: an op (`op`), an API key (`key`) or a UTC day (`day`)<br>one of op · key · day |

### Returns `200` — `data` is `Usage`

The window, its total and its groups

### Errors

| Status | Code and when |
| --- | --- |
| 400 | - `invalid_param` on `groupBy` — not `op`, `key` or `day`<br>- `invalid_param` on `from` / `to` — neither `YYYY-MM-DD` nor an ISO-8601 instant<br>- `invalid_param` on `from` — not before `to`, or the window spans more than 366 days |

## Objects

Each described once; a linked type is another object on this page.

### Bucket

What was spent in one group, or in the whole window

| Field | Type | Description |
| --- | --- | --- |
| credits | integer (int64) | Credits charged, for the jobs created in the window |
| items | integer (int64) | Items of those jobs that settled |
| jobs | integer (int64) | Jobs created in the window |
| key | string | The group: an op name (or the raw type of a job submitted without one), an API key id or `console`, or a UTC date `YYYY-MM-DD`. Absent on the total |
| sync | integer (int64) | Synchronous calls that succeeded and counted against the processing allowance |

### Usage

Usage over one window: its bounds, the grouping, the total and one bucket per group

| Field | Type | Description |
| --- | --- | --- |
| from | string (date-time) | Start of the window, inclusive |
| groupBy | string | What each group is<br>one of op · key · day |
| groups | Bucket[] | One bucket per op, key or day that has any usage, ordered by `key` |
| to | string (date-time) | End of the window, exclusive |
| total | Bucket | The window's totals — the sum of the groups |