Get Usage
const url = 'https://agents.lumalabs.ai/v1/usage';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://agents.lumalabs.ai/v1/usage \ --header 'Authorization: Bearer <token>'Query usage for the current billing period, or for an explicit start/end window.
metadata.<key>=<value> (repeatable, AND-ed) narrows group_by=tenant_id and
group_by=metadata to sessions carrying those tags, as on GET /v1/sessions.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters”Responses
Section titled “ Responses ”Successful Response
object
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.
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
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.
Distinct sessions among the generations and storyboards counted in total_credits_used. Charges that carry no session are not counted.
object
object
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
object
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
object
object
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
object
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
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
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
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.
Credits per value of one session metadata key, across the same lanes as TenantUsageResponse.
object
End of the reported window, exclusive.
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.
Start of the reported window, inclusive.
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.
Example
{ "overage_credits": 0, "period_source": "subscription"}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}