--- title: Session Snapshot | Luma Agents --- GET /v1/sessions/{session\_id} Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/sessions/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://agents.lumalabs.ai/v1/sessions/example \ --header 'Authorization: Bearer ' ``` - Productionagents.lumalabs.ai/v1/sessions/{session\_id} 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 - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Path Parameters **session\_id** required *Session Id* string ## Responses ### 200 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](#tab-panel-0-0) - [null](#tab-panel-0-1) *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 null **created\_at** required *Created At* string format: date-time **deliveries** *Deliveries* Array\ *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](#tab-panel-1-0) - [integer](#tab-panel-1-1) - [number](#tab-panel-1-2) string integer number **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\ **callback\_url** Any of: - [string](#tab-panel-2-0) - [null](#tab-panel-2-1) string null **judge\_calls\_remaining** Any of: - [integer](#tab-panel-3-0) - [null](#tab-panel-3-1) integer null **platform\_skills** *Platform Skills* The platform skills on the agent's menu, by slug (`platform-`). The agent reads them with read\_skill. Array\ **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\ **error\_code** Any of: - [string](#tab-panel-4-0) - [null](#tab-panel-4-1) string null **error\_message** Any of: - [string](#tab-panel-5-0) - [null](#tab-panel-5-1) string null **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\ *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\ **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\ *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\ *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\ *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](#tab-panel-6-0) - [null](#tab-panel-6-1) *PendingConsent* The current unanswered billing offer, using the same shape as its event. object **agent** Any of: - [string](#tab-panel-7-0) - [null](#tab-panel-7-1) string null **expires\_at** Any of: - [string](#tab-panel-8-0) - [null](#tab-panel-8-1) string null **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](#tab-panel-9-0) - [null](#tab-panel-9-1) string null **seq** Any of: - [integer](#tab-panel-10-0) - [null](#tab-panel-10-1) integer null **type** required *Type* string Allowed value: consent\_required **units** required *Units* The priced lines the hold is the sum of. Array\ *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 null **pending\_tool\_invocations** *Pending Tool Invocations* Array\ *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](#tab-panel-11-0) - [null](#tab-panel-11-1) string format: date-time null **invocation\_id** required *Invocation Id* string **params** *Params* object ***key*** additional properties any **run\_id** Any of: - [string](#tab-panel-12-0) - [null](#tab-panel-12-1) string null **tool\_name** required *Tool Name* string **plan\_artifact** Any of: - [PlanArtifactSnapshot](#tab-panel-13-0) - [null](#tab-panel-13-1) *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](#tab-panel-14-0) - [null](#tab-panel-14-1) string null null **session\_id** required *Session Id* string **skills** *Skills* The skill versions this session pinned at creation. Empty when none were attached. Array\ *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 ```json { "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 } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```