Skip to content
Agents
Sessions

Session Snapshot

GET
/v1/sessions/{session_id}
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.

session_id
required
Session Id
string

Successful Response

Media typeapplication/json
SessionSnapshotResponse

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
app
Any of:
AppRef

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
package_digest
required
Package Digest

Sealed package digest of that release.

string
slug
required
Slug

Registered app slug, as named in POST /v1/sessions {app}.

string
version
required
Version

SemVer of the release that was active at session creation.

string
created_at
required
Created At
string format: date-time
deliveries
Deliveries
Array<object>
DeliverySnapshot

A committed session delivery. It carries no URL: read a ready one by its artifact_id through the session's asset read.

object
artifact_id
required
Artifact Id
string
coordinates
required
Coordinates
object
key
additional properties
Any of:
string
document_revision
required
Document Revision
integer
relation
required
Relation
string
Allowed values: capture export
state
required
State
string
Allowed values: pending ready rejected
effective
SessionEffective

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
app_tools
App Tools

The workflow-app tools the agent holds: list_apps, start_app and, on a root session, answer_gate.

Array<string>
callback_url
Any of:
string
judge_calls_remaining
Any of:
integer
platform_skills
Platform Skills

The platform skills on the agent's menu, by slug (platform-<slug>). The agent reads them with read_skill.

Array<string>
platform_tools
Platform Tools

The platform tools the agent holds, by name: the platform_tools menu (search_web, download_web_asset, read, search_for_assets, judge_tool).

Array<string>
error_code
Any of:
string
error_message
Any of:
string
metadata
Metadata

The tags supplied at session creation. Empty when none were set.

object
key
additional properties
string
pending
Pending

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.

Array<object>
PendingAction

One thing the session is waiting on the caller for. Answer it by its domain id.

object
action_id
Action Id

Connector_action: answer with user.connector_action.

string
answer_format
GateAnswerFormat

Gate: the verdict a typed answer takes and the revision targets it may name.

object
revision_targets
required
Revision Targets

What a revise verdict may name, each sample included; empty when the gate names none.

Array<string>
verdict_schema
required
Verdict Schema

JSON schema of the verdict.

object
key
additional properties
any
answer_type
Answer Type

The input type that answers it. Send this type; kind alone does not determine it.

string
Allowed values: user.tool_result user.gate_verdict user.consent
event_id
Event Id

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.

string
expires_at
Expires At
string
hold_credits
Hold Credits

Consent: credits held on accept.

integer
how_to_answer
How To Answer

Gate: how to get the answer from the user and send it.

string
invocation_id
Invocation Id

Custom_tool and gate: the id the answer echoes. answer_type names the input that answers it.

string
kind
required
Kind
string
Allowed values: custom_tool gate consent connector_action
offer
ConsentOffer

Consent: which offer it is. finals is the review's first paid commitment; top_up adds credits to a run that already has one.

string
Allowed values: finals top_up
quote_id
Quote Id

Consent: answer with user.consent.

string
run_id
Run Id
string
show
Show

Gate: the rendered samples the review asks about. Show them to the user before asking.

Array<object>
GateShownAsset

One rendered sample a review gate asks about, named by the revision target a revise verdict uses for it.

object
asset_id
required
Asset Id

The sample render's asset id.

string
target
required
Target

The revision target that names this sample in answer_format.revision_targets.

string
unit
Unit

The ad unit or format the sample was rendered for, e.g. square.

string
text
Text

Gate: the source and translated copy the review asks about, as it stands now. Show it to the user before asking.

Array<object>
GateReviewText

One line of copy a review gate asks a person to approve: text to show, not instructions.

object
label
required
Label

The language and role of the copy, e.g. English · headline.

string
target
required
Target

The revision target that owns this copy in answer_format.revision_targets.

string
text
required
Text

The current copy to approve, including the user's own edits.

string
units
Units

Consent: the priced lines hold_credits is the sum of.

Array<object>
QuotedUnitRef

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
dimensions
required
Dimensions

Pricing dimensions for this line, as a flat map of dimension name to value, e.g. resolution to 1080p.

object
key
additional properties
any
quantity
required
Quantity

Number of units on this line.

integer
rate_credits
required
Rate Credits

Credits per unit. Zero means unpriced in this environment, never free.

integer
tier
required
Tier

Pricing tier these units are rated against, e.g. the app-declared action type.

string
pending_consent
Any of:
PendingConsent

The current unanswered billing offer, using the same shape as its event.

object
agent
Any of:
string
expires_at
Any of:
string
hold_credits
required
Hold Credits

Credits this quote would add to the run, held on accept.

integer
quote_id
required
Quote Id

Identifier of the offered quote, echoed back on accept.

string
reason
required
Reason

Why more money is being asked for.

string
Allowed values: regenerate command overrun
run_id
Any of:
string
seq
Any of:
integer
type
required
Type
string
Allowed value: consent_required
units
required
Units

The priced lines the hold is the sum of.

Array<object>
QuotedUnitRef

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
dimensions
required
Dimensions

Pricing dimensions for this line, as a flat map of dimension name to value, e.g. resolution to 1080p.

object
key
additional properties
any
quantity
required
Quantity

Number of units on this line.

integer
rate_credits
required
Rate Credits

Credits per unit. Zero means unpriced in this environment, never free.

integer
tier
required
Tier

Pricing tier these units are rated against, e.g. the app-declared action type.

string
pending_tool_invocations
Pending Tool Invocations
Array<object>
PendingToolInvocation

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.

object
expires_at
Any of:
string format: date-time
invocation_id
required
Invocation Id
string
params
Params
object
key
additional properties
any
run_id
Any of:
string
tool_name
required
Tool Name
string
plan_artifact
Any of:
PlanArtifactSnapshot

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.

object
data
required
Data

The artifact document (shape per schema_ref).

object
key
additional properties
any
revision
required
Revision

Monotonic revision, bumped on every mutation.

integer
schema_ref
Any of:
string
session_id
required
Session Id
string
skills
Skills

The skill versions this session pinned at creation. Empty when none were attached.

Array<object>
SessionSkill

A skill version a session pinned at creation.

object
name
required
Name
string
skill_id
required
Skill Id
string
version
required
Version

The version this session reads; latest already resolved.

integer
state
required
SessionState
string
Allowed values: active closing suspended error completed expired
status
SessionStatus

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.

string
default: idle
Allowed values: running idle terminated
turn_running
Turn Running

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.

boolean
updated_at
required
Updated At
string format: date-time
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

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