Skip to content
Agents
Sessions

Session Usage

GET
/v1/sessions/{session_id}/usage
curl --request GET \
--url https://agents.lumalabs.ai/v1/sessions/example/usage \
--header 'Authorization: Bearer <token>'

What a session and every session it started cost, by stage and by job.

Each stage line carries its credits with the LLM tokens and calls behind them, and each job line carries its credits and whether they are still an estimate. total_credits is the session total.

session_id
required
Session Id
string

Successful Response

Media typeapplication/json
SessionUsageRollup

Payload for GET /v1/sessions/{id}/usage and the BFF mirror.

object
jobs
Jobs
Array<object>
JobUsage

What one generation dispatch cost.

Deliberately not a job state: GET /v1/sessions/{id}/jobs owns that answer and derives it from the artifacts, so a second, weaker copy here would be a drift surface. The two join on job_id.

object
credits
required
Credits
integer
credits_estimated
required
Credits Estimated
boolean
job_id
required
Job Id
string
model
Any of:
string
session_id
required
Session Id
string
stages
Stages
Array<object>
StageUsage

Rollup line for one stage bucket of a session.

object
cache_creation_input_tokens
Cache Creation Input Tokens
integer
0
cache_read_input_tokens
Cache Read Input Tokens
integer
0
credits
required
Credits
integer
event_count
required
Event Count
integer
generation_count
required
Generation Count
integer
input_tokens
required
Input Tokens
integer
llm_call_count
required
Llm Call Count
integer
output_tokens
required
Output Tokens
integer
stage
required
Stage
string
total_credits
required
Total Credits
integer
unresolved_event_count
required
Unresolved Event Count
integer
Example
{
"stages": [
{
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
]
}

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"
}
]
}