Skip to content
Agents
Usage and credits

Get Usage

GET
/v1/usage
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.

group_by
Any of:
string
Allowed values: model user session api_key tenant_id metadata

Group by: model, user, session, api_key, tenant_id, metadata

user_id
Any of:
string

Filter by client_user_id (for group_by=session)

tenant_id
Any of:
string
<= 256 characters

Filter by the session token's tenant_id (for group_by=tenant_id or group_by=metadata)

metadata_key
Any of:
string

The session metadata key to group by (required for group_by=metadata)

start
Any of:
string format: date-time

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 format: date-time

End of an explicit window (ISO-8601, exclusive; default now). Requires start.

Successful Response

Media typeapplication/json
Any of:
UsageSummaryResponse
object
included_credits
Any of:
integer
included_credits_remaining
Any of:
integer
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
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
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
Example
{
"overage_credits": 0,
"period_source": "subscription"
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}