# Usage

Usage shows what the organisation has used: the work done and the tokens it took, and the cloud storage its kept files take up. It never shows cost.

Usage shows what the organisation has used: the work done and the tokens it took, and the cloud storage its kept files take up. It never shows cost.

## The Usage report object

The usage object is one row of work for a period and a grouping.

- `bucket` (string (date-time), required): Start of the day or week (UTC); for group=all, `from`.
- `keys` (object, required): Each `by` dimension to its value.
- `runs` (integer, required): Runs started in this period.
- `formatsBuilt` (integer, required): Formats planned or reviewed (flagged or not).
- `retries` (integer, required): Retried plans, and plans made again (Try again).
- `failures` (integer, required): Formats that failed.
- `inputTokens` (integer, required): Includes cached input.
- `outputTokens` (integer, required): Tokens the organisation's runs produced in this period.
- `motion` (integer, required): Animated sizes that finished rendering, by when they finished.

```json
{
  "bucket": "string",
  "keys": {},
  "runs": 0,
  "formatsBuilt": 0,
  "retries": 0,
  "failures": 0,
  "inputTokens": 0,
  "outputTokens": 0,
  "motion": 0
}
```

## Retrieve work usage

`GET /api/v1/usage/work`

Permission: Usage · Read.

Returns the organisation's work and tokens, in buckets by day or month and grouped by `campaign`, `site` and/or `format` (choose 1 to 3 with `by`). Runs, formats built and failures are counted by when the run started; retries and tokens by when they happened. A run counts once per group, so a run with two formats counts in both format rows. Test runs never count. Cost is not shown.

### Parameters

- `from` (string (date), optional): First UTC day, inclusive (default 30 days before `to`).
- `to` (string (date), optional): Last UTC day, inclusive (default today). The range is at most 366 days.
- `group` (string, optional):  One of: `day`, `week`, `all`.
- `by` (string, optional): Comma-separated, 1 to 3 distinct dimensions of `campaign`, `site`, `format` (default `campaign`).
- `site` (string, optional): Filter by brand code.
- `campaign` (string, optional): Filter by campaign key.
- `format` (string, optional): Filter by format key.

### Returns

Work rows, by bucket then keys.

An object with:

- `rows` (array of objects, required):
  - `bucket` (string (date-time), required): Start of the day or week (UTC); for group=all, `from`.
  - `keys` (object, required): Each `by` dimension to its value.
  - `runs` (integer, required): Runs started in this period.
  - `formatsBuilt` (integer, required): Formats planned or reviewed (flagged or not).
  - `retries` (integer, required): Retried plans, and plans made again (Try again).
  - `failures` (integer, required): Formats that failed.
  - `inputTokens` (integer, required): Includes cached input.
  - `outputTokens` (integer, required): Tokens the organisation's runs produced in this period.
  - `motion` (integer, required): Animated sizes that finished rendering, by when they finished.

### Errors

- 400: One of: “from must be a date (YYYY-MM-DD)”; “to must be a date (YYYY-MM-DD)”; “to must not be before from”; “range (from to to) is \<n> days; the most is 366”; “group must be day, week or all”; “by takes at most 3 dimensions, got \<n>”; `by: unknown dimension "<d>"; it must be one of <allowed>`; `by: <d> is listed twice`.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read usage” or “could not check token”.
- 501: “usage is not enabled”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/usage/work \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve storage usage

`GET /api/v1/usage/storage`

Permission: Usage · Read.

Returns how much cloud storage the organisation's kept files (runs, thumbnails, images, review files) use, and the most its plan allows. `keeping` is false, with both numbers 0, when the organisation keeps no work.

### Returns

Cloud storage.

An object with:

- `keeping` (boolean, required):
- `usedBytes` (integer, required):
- `capBytes` (integer, required):

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: A library error.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/usage/storage \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
