Skip to content

API reference

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.

The Usage report object

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

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.

Retrieve work usage

PermissionUsage · 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.

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

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

401invalid_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).

409api_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”

Retrieve storage usage

PermissionUsage · 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:

  • keepingbooleanRequired
  • usedBytesintegerRequired
  • capBytesintegerRequired

Errors

StatusCodeMeaning
401invalid_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).

409api_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.