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.
Query parameters
fromstring (date)Optional
First UTC day, inclusive (default 30 days before to).
tostring (date)Optional
Last UTC day, inclusive (default today). The range is at most 366 days.
groupstringOptional
Possible valuesdayweekall
Default"day"
bystringOptional
Comma-separated, 1 to 3 distinct dimensions of campaign,
site, format (default campaign).
sitestringOptional
Filter by brand code.
campaignstringOptional
Filter by campaign key.
formatstringOptional
Filter by format key.
Returns
Work rows, by bucket then keys.
An object with:
rowsarray of objectsRequired
Show child attributesHide child attributes
bucketstring (date-time)Required
Start of the day or week (UTC); for group=all, from.
keysobjectRequired
Each by dimension to its value.
runsintegerRequired
Runs started in this period.
formatsBuiltintegerRequired
Formats planned or reviewed (flagged or not).
retriesintegerRequired
Retried plans, and plans made again (Try again).
failuresintegerRequired
Formats that failed.
inputTokensintegerRequired
Includes cached input.
outputTokensintegerRequired
Tokens the organisation’s runs produced in this period.
motionintegerRequired
Animated sizes that finished rendering, by when they finished.
Errors
Status
Code
Meaning
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”.
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:
keepingbooleanRequired
usedBytesintegerRequired
capBytesintegerRequired
Errors
Status
Code
Meaning
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.