Usage

Usage over a window, grouped

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
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

Query parameters

fromstring

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.

tostring

End of the window, exclusive — 2026-10-01 ends with the last instant of 30 September. Same formats. Defaults to now.

groupBy'op' | 'key' | 'day'

What a group is: an op (op), an API key (key) or a UTC day (day)

Response

The window, its total and its groups

Changes

No recorded changes to this operation across all 1 revision of this API.