Session Snapshot
const url = 'https://agents.lumalabs.ai/v1/sessions/example';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/sessions/example \ --header 'Authorization: Bearer <token>'Read-only session snapshot: state, plan artifact, pending gates.
The initial-load / reconnect surface for orchestrated-session clients
(a studio frontend renders its workflow from plan_artifact and its
approval footer from pending_tool_invocations, then resumes SSE).
Cheap by design: one row read plus an indexed LIMIT-1 message peek (for
turn_running), plus the delivery rows of an app that takes deliveries;
no history join — read GET /events for the conversation. effective
adds the session's billing resolve, its platform-skill view and, for a
session holding judge_tool, a scan of its tool calls.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Responses
Section titled “ Responses ”Successful Response
Read-only session snapshot (GET /v1/sessions/{id}) — the reconnect / initial-load surface: current state, the plan artifact, and any pending client-tool invocations (e.g. a review gate awaiting a verdict).
object
The workflow app a session is running, frozen at creation. package_digest is the sealed digest of the release that served the session's configuration — the identity two runs are compared by, since a version label can be reused.
object
Sealed package digest of that release.
Registered app slug, as named in POST /v1/sessions {app}.
SemVer of the release that was active at session creation.
A committed session delivery. It carries no URL: read a ready one by its artifact_id through the session's asset read.
The tools, skills, judge budget and callback the session's agent holds at its next turn, read now: a tool or skill Luma has withdrawn since create is gone from here too.
object
The workflow-app tools the agent holds: list_apps, start_app and, on a root session, answer_gate.
The platform skills on the agent's menu, by slug (platform-<slug>). The agent reads them with read_skill.
The platform tools the agent holds, by name: the platform_tools menu (search_web, download_web_asset, read, search_for_assets, judge_tool).
The tags supplied at session creation. Empty when none were set.
object
Everything the session is waiting on the caller for — the same list the last session.status_idle carried as requires_action. Answer each by its domain id.
One thing the session is waiting on the caller for. Answer it by its domain id.
object
Connector_action: answer with user.connector_action.
Gate: the verdict a typed answer takes and the revision targets it may name.
object
What a revise verdict may name, each sample included; empty when the gate names none.
JSON schema of the verdict.
object
The input type that answers it. Send this type; kind alone does not determine it.
Id of the blocking event (agent.custom_tool_use, agent.gate, session.consent_required, connector.action_required), for display and de-duplication. Absent when that event is not in the log; key answers on invocation_id, quote_id or action_id.
Consent: credits held on accept.
Gate: how to get the answer from the user and send it.
Custom_tool and gate: the id the answer echoes. answer_type names the input that answers it.
Consent: which offer it is. finals is the review's first paid commitment; top_up adds credits to a run that already has one.
Consent: answer with user.consent.
Gate: the rendered samples the review asks about. Show them to the user before asking.
One rendered sample a review gate asks about, named by the revision target a revise verdict uses for it.
object
The sample render's asset id.
The revision target that names this sample in answer_format.revision_targets.
The ad unit or format the sample was rendered for, e.g. square.
Gate: the source and translated copy the review asks about, as it stands now. Show it to the user before asking.
One line of copy a review gate asks a person to approve: text to show, not instructions.
object
The language and role of the copy, e.g. English · headline.
The revision target that owns this copy in answer_format.revision_targets.
The current copy to approve, including the user's own edits.
Consent: the priced lines hold_credits is the sum of.
One priced line of a quote: a batch of planned finals that share a tier and a set of pricing dimensions. The pricing policy id the server rates against is deliberately not on the wire — it is an internal join key.
object
Pricing dimensions for this line, as a flat map of dimension name to value, e.g. resolution to 1080p.
object
Number of units on this line.
Credits per unit. Zero means unpriced in this environment, never free.
Pricing tier these units are rated against, e.g. the app-declared action type.
The current unanswered billing offer, using the same shape as its event.
object
Credits this quote would add to the run, held on accept.
Identifier of the offered quote, echoed back on accept.
Why more money is being asked for.
The priced lines the hold is the sum of.
One priced line of a quote: a batch of planned finals that share a tier and a set of pricing dimensions. The pricing policy id the server rates against is deliberately not on the wire — it is an internal join key.
object
Pricing dimensions for this line, as a flat map of dimension name to value, e.g. resolution to 1080p.
object
Number of units on this line.
Credits per unit. Zero means unpriced in this environment, never free.
Pricing tier these units are rated against, e.g. the app-declared action type.
One unresolved client-tool invocation the session is suspended on.
Answer with a user.tool_result (or user.gate_verdict) on POST /v1/sessions/{session_id}/events.
The optional run_id correlates an explicit execution.
The session's typed plan artifact as stored — schema_ref names the
registered schema the data payload validates against (e.g.
ad_variant_set/v1); None marks an ad-hoc skill-declared schema.
The skill versions this session pinned at creation. Empty when none were attached.
A skill version a session pinned at creation.
object
The version this session reads; latest already resolved.
Running while the session advances without client input; idle when it waits for the next message or for everything in pending; terminated once it takes no more work.
True while the session will still advance without client input — an agent turn is queued or executing, or in-flight jobs will resume the agent when they finish. False once the session has settled: it is terminal, suspended on a pending tool invocation, or waiting for the next client message.
Example
{ "deliveries": [ { "relation": "capture", "state": "pending" } ], "pending": [ { "answer_type": "user.tool_result", "kind": "custom_tool", "offer": "finals" } ], "pending_consent": { "reason": "regenerate", "type": "consent_required" }, "state": "active", "status": "running", "turn_running": false}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}