Get team usage breakdown

Returns credit usage for the authenticated key’s enterprise account, grouped by one or more dimensions.

GET https://agents.lumalabs.ai/v1/team/usage-breakdown

This endpoint requires an Admin read-only key. Send it as a Bearer token in the Authorization header.

Minimal request

The request covers the top-level enterprise account and all its subteams. group_by is the only required query parameter. It may be repeated to create a multidimensional report.

The following request returns usage grouped by user. With no time parameters, the endpoint reports the trailing 30 days.

curl --fail-with-body --get \
  "https://agents.lumalabs.ai/v1/team/usage-breakdown" \
  -H "Authorization: Bearer ${LUMA_ADMIN_API_KEY}" \
  --data-urlencode "group_by=user"

Examples

Team → project → board → user for the last 24 hours

The following query reports usage from the last 24 hours, grouped by team (group_by=subteam), project, board, and user. The timestamps below define one 24-hour window; replace them with the UTC bounds you want to report.

curl --fail-with-body --get \
  "https://agents.lumalabs.ai/v1/team/usage-breakdown" \
  -H "Authorization: Bearer ${LUMA_ADMIN_API_KEY}" \
  --data-urlencode "group_by=subteam" \
  --data-urlencode "group_by=project" \
  --data-urlencode "group_by=board" \
  --data-urlencode "group_by=user" \
  --data-urlencode "query_start_time=2026-09-21T12:00:00Z" \
  --data-urlencode "query_end_time=2026-09-22T12:00:00Z"

The API response contains the same data shown in the application’s usage table, represented as JSON. For this query, a representative table looks like:

| Team      | Project        | Board / API key   | User       | Credits |
|-----------|----------------|-------------------|------------|---------|
| Design    | (null)         | Concept scratch   | Alex Chen  |     180 |
| Design    | Fall campaign  | Launch assets     | Alex Chen  |     506 |
| Design    | Fall campaign  | Product shots     | Sam Rivera |     284 |
| Marketing | Holiday launch | Social teasers    | Priya Shah |     120 |
| Marketing | Holiday launch | Product demo      | Jordan Lee |      90 |
| Marketing | Brand refresh  | Style exploration | Morgan Yu  |      60 |

Here (null) under the Project column means that the usage was on a board that is not inside any project.

Project → board for all available history

The API has no all_time period value. To report all available history, set query_start_time to a timestamp at or before the account’s first usage and omit query_end_time, which then defaults to now.

curl --fail-with-body --get \
  "https://agents.lumalabs.ai/v1/team/usage-breakdown" \
  -H "Authorization: Bearer ${LUMA_ADMIN_API_KEY}" \
  --data-urlencode "group_by=project" \
  --data-urlencode "group_by=board" \
  --data-urlencode "query_start_time=1970-01-01T00:00:00Z"

The API response contains the same data shown in the application’s usage table, represented as JSON. For this query, a representative table looks like:

| Project       | Board / API key | Credits |
|---------------|-----------------|---------|
| Fall campaign | Launch assets   |   8,412 |
| Fall campaign | Product shots   |   3,208 |
| Fall campaign | Campaign cuts   |   2,117 |
| Brand library | Hero concepts   |   1,104 |
| Brand library | Style guide     |     842 |
| Product launch | Demo reel      |     736 |

Query parameters

Parameter	Required or default	Description
group_by	Required; repeatable	One or more grouping dimensions. Supported values: subteam, user, board, project, product, model, media, role, date, week, and month. Order matters.
period	Optional	Billing-period window: current_period or last_period. Cannot be combined with query_start_time or query_end_time.
query_start_time	Default: 30 days ago	ISO 8601 timestamp. May be provided without query_end_time. Cannot be combined with period.
query_end_time	Default: now	ISO 8601 timestamp. May be provided without query_start_time. Cannot be combined with period.
board_ids	Optional; repeatable	Restrict results to one or more board UUIDs.
search	Optional	Case-insensitive substring search over visible, searchable grouped fields. At most five whitespace-separated terms are used.
limit	Default: 500	Maximum rows to return. Minimum 1; maximum 1000.
offset	Default: 0	Number of grouped rows to skip. Minimum 0.
project_attribution	Default: at_spend_time	at_spend_time uses the project recorded when credits were spent. current follows the board’s current project membership.
tz_name	Default: UTC	IANA timezone name used for date, week, and month buckets, such as America/Los_Angeles. Ignored when no calendar dimension is selected.

Choose a time window

Use one of these three forms:

Window	Parameters
Billing period	period=current_period or period=last_period
Custom window	Either or both of query_start_time and query_end_time
Trailing 30 days	Omit period, query_start_time, and query_end_time

If only query_start_time is provided, the end defaults to now. If only query_end_time is provided, the start defaults to 30 days before the request is processed. period is mutually exclusive with either explicit timestamp.

Grouping dimensions

Repeat group_by to select multiple dimensions. The order is significant: the first dimension defines the primary result sections and affects ordering.

Dimension	Returned data
subteam	The subteam billed for the usage. Direct usage by the enterprise account has a null subteam.
user	User ID and, when the user can be resolved, email, full name, and profile-media URL. API usage without a user remains in a null bucket.
board	Board ID and name. API usage without a board can instead carry companion API-key fields.
project	Project ID and name, interpreted according to project_attribution.
product	Product surface: Canvas, API, or Apps.
model	Customer-facing model category.
media	Customer-facing media category.
role	User role: owner, admin, member, or guest.
date	Calendar-day bucket.
week	Calendar-week bucket beginning Monday.
month	Calendar-month bucket represented by its first day.

api_key is not a grouping dimension. When board is selected, API usage that has no board can populate api_key_id, api_key_name, api_key_prefix, and api_key_revoked so separate integrations do not collapse into a single “No Board” row.

Null dimension values are intentionally retained. They represent usage that could not be attributed to that dimension and ensure grouped totals do not silently omit credits.

Search visible values

Search is applied before grouping and pagination. Each whitespace-separated term must match, while each term may match any searchable field currently visible through group_by.

Searchable grouped fields include:

• subteam name for enterprise account rollups;
• user name or email;
• board name or an API-key display name shown in the board column;
• project name;
• product, model, and media labels.

Response

The response has a stable envelope and a wide row schema. Fields for unselected dimensions are returned as null.

The following response is abbreviated for readability: it shows two rows with their populated fields. The ellipses represent fields and additional rows omitted from the example; they are not part of the JSON returned by the API.

{
  "team_id": "1048cee0-308d-415b-8772-6eb159a37dae",
  "query_start_time": "2026-09-21T12:00:00",
  "query_end_time": "2026-09-22T12:00:00",
  "group_by": ["subteam", "project", "board", "user"],
  "rows": [
    {
      "subteam_id": "d4ee8b79-6335-440f-9062-8b344a30bb2a",
      "subteam_name": "Design",
      "project_id": "320d4c14-ef09-4a28-9da9-c2621c852ba1",
      "project_name": "Fall campaign",
      "board_id": "40f985a8-17cf-4614-95b3-812d2bc105d7",
      "board_name": "Launch assets",
      "user_id": "ceb00ea1-496b-5058-8395-44efb2d9de14",
      "user_email": "xyz@abc.com",
      "user_full_name": "Alex Chen",
      "total_credits": 506,
      "last_activity_at": "2026-09-22T10:50:10.938684",
      // ... null-valued fields omitted
    },
    {
      "subteam_id": "d4ee8b79-6335-440f-9062-8b344a30bb2a",
      "subteam_name": "Design",
      "project_id": "320d4c14-ef09-4a28-9da9-c2621c852ba1",
      "project_name": "Fall campaign",
      "board_id": "67134f23-f04b-4b1b-a538-b230c322b9f6",
      "board_name": "Product shots",
      "user_id": "0315112e-26d2-4d82-9d1d-737e790de5a4",
      "user_email": "sam@example.com",
      "user_full_name": "Sam Rivera",
      "total_credits": 284,
      "last_activity_at": "2026-09-22T09:31:45.216842",
      // ... null-valued fields omitted
    },
    // ... additional rows omitted
  ],
  "total_credits": 1240,
  "total_rows": 8,
  // ... remaining envelope fields omitted
}

Response envelope

Field	Type	Description
team_id	UUID	Enterprise account selected by the authenticated key.
query_start_time	datetime	Resolved start of the query window.
query_end_time	datetime	Resolved end of the query window.
group_by	string[]	Grouping dimensions in request order.
rows	object[]	Grouped usage rows for the current page.
total_credits	integer	Credits across the complete filtered query, independent of pagination.
total_rows	integer	Number of grouped combinations across the complete filtered query.
distinct_subteams	integer	Distinct non-null subteams when subteam is selected; otherwise 0.
distinct_users	integer	Distinct non-null users when user is selected; otherwise 0.
distinct_boards	integer	Distinct board/API-key values, including an unattributed bucket when present; otherwise 0.
distinct_projects	integer	Distinct non-null projects when project is selected; otherwise 0.
distinct_products	integer	Distinct non-null products when product is selected; otherwise 0.
distinct_models	integer	Distinct non-null models when model is selected; otherwise 0.
distinct_media	integer	Distinct non-null media values when media is selected; otherwise 0.
distinct_roles	integer	Distinct non-null roles when role is selected; otherwise 0.
distinct_dates	integer	Distinct non-null date buckets when date is selected; otherwise 0.
distinct_weeks	integer	Distinct non-null week buckets when week is selected; otherwise 0.
distinct_months	integer	Distinct non-null month buckets when month is selected; otherwise 0.
has_more	boolean	Whether more rows remain after the current page.

Usage row

Every object in rows contains these fields:

Fields	Description
subteam_id, subteam_name	Subteam identity and display name.
user_id, user_email, user_full_name, user_profile_media_url	User identity and display fields. Display fields can be null when the user cannot be resolved.
board_id, board_name	Board identity and display name.
project_id, project_name	Project identity and display name.
product	Product surface.
api_key_id, api_key_name, api_key_prefix, api_key_revoked	Companion API-key attribution on applicable board-grouped rows.
model, media, role	Model, media, and user-role dimensions.
date, week, month	Calendar bucket fields.
total_credits	Credits attributed to this combination of dimensions.
last_activity_at	Timestamp of the most recent credit-ledger entry in this group, or null.

Ordering and pagination

The first group_by dimension defines the primary sections. Sections with the highest total credit usage are returned first; combinations within each section are ordered by total_credits descending.

total_credits, total_rows, and the distinct_* values describe the complete filtered query and do not shrink when limit or offset is applied.

When has_more is true, add the number of rows received to offset and request the next page:

curl --fail-with-body --get \
  "https://agents.lumalabs.ai/v1/team/usage-breakdown" \
  -H "Authorization: Bearer ${LUMA_ADMIN_API_KEY}" \
  --data-urlencode "group_by=user" \
  --data-urlencode "limit=500" \
  --data-urlencode "offset=500"

Errors

Status	Meaning	Common cause
400	Bad request	Invalid tz_name when a calendar dimension uses it.
401	Unauthenticated	Missing, invalid, or revoked Bearer key.
403	Forbidden	The key is not an Admin read-only key with usage access, or its enterprise account is unavailable. Generation keys receive this response.
404	Not found	The requested billing period does not exist, or project reporting is unavailable for the request.
422	Validation failure	Missing or invalid group_by, invalid enum/range/UUID/datetime, or period combined with an explicit timestamp.
429	Rate limited	The request reached the API-wide abuse-prevention backstop. Retry according to the response headers.

All error responses use a detail field:

{
  "detail": "Human-readable error message"
}

Return to the Admin API overview for key creation, credential scope, and rotation guidance.