--- title: Get Usage | Luma Agents --- GET /v1/usage Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/usage'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://agents.lumalabs.ai/v1/usage \ --header 'Authorization: Bearer ' ``` - Productionagents.lumalabs.ai/v1/usage Query usage for the current billing period, or for an explicit `start`/`end` window. `metadata.=` (repeatable, AND-ed) narrows group\_by=tenant\_id and group\_by=metadata to sessions carrying those tags, as on `GET /v1/sessions`. ## Authorizations - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Query Parameters **group\_by** Any of: - [string](#tab-panel-0-0) - [null](#tab-panel-0-1) string Allowed values: model user session api\_key tenant\_id metadata null Group by: model, user, session, api\_key, tenant\_id, metadata **user\_id** Any of: - [string](#tab-panel-1-0) - [null](#tab-panel-1-1) string null Filter by client\_user\_id (for group\_by=session) **tenant\_id** Any of: - [string](#tab-panel-2-0) - [null](#tab-panel-2-1) string <= 256 characters null Filter by the session token's tenant\_id (for group\_by=tenant\_id or group\_by=metadata) **metadata\_key** Any of: - [string](#tab-panel-3-0) - [null](#tab-panel-3-1) string null The session metadata key to group by (required for group\_by=metadata) **start** Any of: - [string](#tab-panel-4-0) - [null](#tab-panel-4-1) string format: date-time null Start of an explicit window (ISO-8601, inclusive; naive times are UTC). Omit both start and end for the current billing period (the UTC calendar month when the plan has no period end). Max 92 days. **end** Any of: - [string](#tab-panel-5-0) - [null](#tab-panel-5-1) string format: date-time null End of an explicit window (ISO-8601, exclusive; default now). Requires start. ## Responses ### 200 Successful Response Media typeapplication/json Any of: - [UsageSummaryResponse](#tab-panel-6-0) - [ModelUsageResponse](#tab-panel-6-1) - [UserUsageResponse](#tab-panel-6-2) - [SessionUsageResponse](#tab-panel-6-3) - [ApiKeyUsageResponse](#tab-panel-6-4) - [TenantUsageResponse](#tab-panel-6-5) - [MetadataUsageResponse](#tab-panel-6-6) *UsageSummaryResponse* object **included\_credits** Any of: - [integer](#tab-panel-7-0) - [null](#tab-panel-7-1) integer null **included\_credits\_remaining** Any of: - [integer](#tab-panel-8-0) - [null](#tab-panel-8-1) integer null **overage\_credits** *Overage Credits* Credits consumed past the granted allowance; 0 without a plan or when overage is not billed. Measured as the billing pool's settled usage across every surface (API, MCP and the Luma app) against the credits the period actually granted, unlike total\_credits\_used, which counts external API generations and storyboards only. integer 0 **overage\_rate** Any of: - [string](#tab-panel-9-0) - [null](#tab-panel-9-1) string null **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string **plan\_slug** Any of: - [string](#tab-panel-10-0) - [null](#tab-panel-10-1) string null **total\_credits\_used** required *Total Credits Used* Settled credits for external API generations and storyboards in this billing period. Excludes direct MCP and Luma app activity; MCP usage without a session\_id reports team-wide credits. integer **total\_generations** required *Total Generations* integer **total\_sessions** required *Total Sessions* Distinct sessions among the generations and storyboards counted in total\_credits\_used. Charges that carry no session are not counted. integer *ModelUsageResponse* object **groups** required *Groups* Array\ *ModelUsage* object **action** required *Action* string **count** required *Count* integer **model** required *Model* string **total\_credits** required *Total Credits* integer **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string *UserUsageResponse* object **groups** required *Groups* Array\ *UserUsage* object **sessions** required *Sessions* integer **total\_credits** required *Total Credits* integer **user\_id** required Any of: - [string](#tab-panel-11-0) - [null](#tab-panel-11-1) string null **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string *SessionUsageResponse* object **groups** required *Groups* Array\ *SessionUsageItem* object **generation\_count** required *Generation Count* integer **session\_id** required *Session Id* string **total\_credits** required *Total Credits* integer **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string *ApiKeyUsageResponse* object **groups** required *Groups* Array\ *ApiKeyUsage* object **api\_key\_id** required Any of: - [string](#tab-panel-12-0) - [null](#tab-panel-12-1) string null **metadata** *Metadata* object ***key*** additional properties string **name** Any of: - [string](#tab-panel-13-0) - [null](#tab-panel-13-1) string null **sessions** required *Sessions* integer **total\_credits** required *Total Credits* integer **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string *TenantUsageResponse* Credits per tenant, across every lane a session spends through: generations, storyboards, the session's own model turns, and the GPU actions it runs. object **groups** required *Groups* Array\ *TenantUsage* object **sessions** required *Sessions* Root sessions with spend in the window. A child session's spend counts toward its root. integer **tenant\_id** required Any of: - [string](#tab-panel-14-0) - [null](#tab-panel-14-1) string null **total\_credits** required *Total Credits* integer **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string **unattributed\_credits** required *Unattributed Credits* Credits from /v1 generations, storyboards and session model turns in the window whose session no longer exists, so it cannot be grouped. Counts only spend charged to this client's API keys, and is not narrowed by the tenant\_id or metadata filters. integer *MetadataUsageResponse* Credits per value of one session metadata key, across the same lanes as TenantUsageResponse. object **groups** required *Groups* Array\ *MetadataUsage* object **sessions** required *Sessions* Root sessions with spend in the window. A child session's spend counts toward its root. integer **total\_credits** required *Total Credits* integer **value** required Any of: - [string](#tab-panel-15-0) - [null](#tab-panel-15-1) string null **metadata\_key** required *Metadata Key* string **period\_end** required *Period End* End of the reported window, exclusive. string **period\_source** required *UsagePeriodSource* Where the window came from: `subscription` is the team's current billing period; `calendar_month` is the current UTC calendar month, used when the plan has no period end (pay-as-you-go); `explicit` is the caller's start/end. string Allowed values: subscription calendar\_month explicit **period\_start** required *Period Start* Start of the reported window, inclusive. string **unattributed\_credits** required *Unattributed Credits* Credits from /v1 generations, storyboards and session model turns in the window whose session no longer exists, so it cannot be grouped. Counts only spend charged to this client's API keys, and is not narrowed by the tenant\_id or metadata filters. integer ##### Example ```json { "overage_credits": 0, "period_source": "subscription" } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```