--- title: Get team usage breakdown | Luma Agents description: Get enterprise credit usage grouped by subteam, user, board, project, product, model, media, role, or calendar period. --- Returns credit usage for the authenticated key’s enterprise account, grouped by one or more dimensions. ```http GET https://agents.lumalabs.ai/v1/team/usage-breakdown ``` This endpoint requires an [Admin read-only key](/admin-api/index.md). 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. ```bash 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. ```bash 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](https://app.lumalabs.ai/usage) table, represented as JSON. For this query, a representative table looks like: ```text | 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. ```bash 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](https://app.lumalabs.ai/usage) table, represented as JSON. For this query, a representative table looks like: ```text | 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. ```jsonc { "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: ```bash 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: ```json { "detail": "Human-readable error message" } ``` Return to the [Admin API overview](/admin-api/index.md) for key creation, credential scope, and rotation guidance.