Session Events
const url = 'https://agents.lumalabs.ai/v1/sessions/example/events';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/events \ --header 'Authorization: Bearer <token>'One page of the session's event log, in seq order.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”Responses
Section titled “ Responses ”One page of the session's event log, in seq order.
One page of a session's event log, in seq order.
object
An over-cap recorded event: the envelope, its identity fields, and truncated.
object
Tool calls the stopped attempt started that got no result. Empty when it started none.
Durable id of the generated artifact.
The attachment id returned by POST /v1/attachments.
Registered SESSION.* error code.
True when the server resumed after its own jobs finished.
ISO-8601 time the event was recorded.
Remaining credit balance at the time of this warning.
In = a caller input; out = the platform.
Credits this quote would add to the run, held on accept.
Opaque event id (sevt_…).
The seq of the recorded input this failure answers.
Discriminated by 'kind': approve | select | text_input | confirm for an ask_user question (see InteractionRequest in the SDK types for the full shape), or review for an app's review gate, which carries the tool and params it presented.
object
Tool/stage that performed the mutation, e.g. plan_storyboard.
The command the app authorizes the call as.
Identifier of the event that failed delivery.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
Identifier of the offered quote, echoed back on accept.
Retrying — the server is retrying; exhausted — this turn is over, a new input may succeed; terminal — the session cannot continue.
New artifact revision after this mutation.
The run this event belongs to.
Per-feed ordinal.
Skill name (durable slug, inline playbook name, or the name of a partner skill the session attached).
Where the skill came from: a partner skill the session attached (client), or a durable slug on the same menu (slug). inline is reserved and not emitted: inline playbooks are injected, never read.
Why the session went idle. pending is present only for requires_action; code, message and retryable only for error.
object
Error only: the registered session error code.
Error only: a message safe to show the user.
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.
Error only: whether sending the request again could succeed. The session stays open.
Always true: only identity fields were kept.
The wire type.
- AgentCustomToolUseRecord
- AgentDoneRecord
- AgentGateRecord
- AgentMessageRecord
- AgentPreviewRecord
- AgentSkillActivatedRecord
- AgentStartedRecord
- AgentToolResultRecord
- AgentToolUseRecord
- ArtifactAttachmentReadyRecord
- ArtifactReadyRecord
- JobCompletedRecord
- JobFailedRecord
- JobStartedRecord
- PlanUpdatedRecord
- RunCompletedRecord
- RunStartedRecord
- SessionBudgetWarningRecord
- SessionConfigChangedRecord
- SessionConsentRequiredRecord
- SessionContextCompactingRecord
- SessionErrorRecord
- SessionInputFailedRecord
- SessionStatusIdleRecord
- SessionStatusRunningRecord
- SessionStatusTerminatedRecord
- SessionTurnRetriedRecord
- SessionUsageRecord
- StageDoneRecord
- StageStartedRecord
- UserMessageRecord
- UserInterruptRecord
- UserToolResultRecord
- UserGateVerdictRecord
- UserCommandRecord
- UserConsentRecord
A client-side tool invocation. The SDK must call the registered clientToolHandler and answer with the input answer_type names (POST /v1/sessions/{session_id}/events) carrying this invocation_id. The optional run_id correlates explicit executions.
object
The input type that answers this invocation. On a webhook tool call, the type the reply to its delivery takes.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Must be echoed back on the input that answers it.
Input parameters.
object
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Tool name as registered in createSession().
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A sub-agent finished its delegated task.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
One-sentence summary of what the sub-agent accomplished.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The agent is requesting user input to continue. Render the appropriate UI widget and answer with the input answer_type names (POST /v1/sessions/{session_id}/events) carrying interaction.invocation_id. The optional run_id correlates explicit executions.
object
Sub-agent name, present when the event originates from a sub-agent.
The input type that answers this request.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Discriminated by 'kind': approve | select | text_input | confirm for an ask_user question (see InteractionRequest in the SDK types for the full shape), or review for an app's review gate, which carries the tool and params it presented.
object
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The full final text of the most recent assistant turn. Use for replacement if delta accumulation diverged.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Complete text of the assistant message.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The agent is presenting a grid of generated options for user selection.
object
Sub-agent name, present when the event originates from a sub-agent.
Options to display.
A single option in a preview grid.
object
Asset media type.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Whether the user should pick one or multiple.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The agent read a skill for the first time in this session. Fires once per skill per session, on its first successful read or read_skill, and only in a session that attached partner skills; other sessions never emit it.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
The id of the partner skill that was read. Absent for every other source.
Skill name (durable slug, inline playbook name, or the name of a partner skill the session attached).
Where the skill came from: a partner skill the session attached (client), or a durable slug on the same menu (slug). inline is reserved and not emitted: inline playbooks are injected, never read.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The pinned version of the partner skill that was read. Absent for every other source.
The orchestrator delegated work to a named sub-agent.
object
Sub-agent name as defined in createSession().agents.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Brief description of the delegated task.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A tool the server ran finished, successfully or not.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A tool the server runs itself began executing. No client action required — a tool the caller answers announces as agent.custom_tool_use instead.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Stable identifier for this invocation; matches agent.tool_result.
Input parameters passed to the tool.
object
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Tool name.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The artifact ingest pipeline for an uploaded attachment reached a terminal state. status='ready' means moderation passed. status='rejected' means it failed.
object
Sub-agent name, present when the event originates from a sub-agent.
The attachment id returned by POST /v1/attachments.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
'ready' = pipeline passed; 'rejected' = moderation failed.
Presigned URL to thumbnail variant, if generated.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
Presigned GET URL. Expires in 1 hour.
A generated artifact landed at its plan-artifact coordinates (keyframe image, segment video, reference image, or stitched output).
object
Sub-agent name, present when the event originates from a sub-agent.
Durable id of the generated artifact.
Where in the plan artifact this asset landed.
object
Stage that produced the artifact, e.g. render_keyframes.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Presigned URL to a thumbnail variant.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
Presigned URL to the asset. Expires; re-fetch via GET.
A GPU job finished. The server will automatically continue the agent turn.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
Credits this job cost. The settled value when a settlement row exists, otherwise the dispatch estimate. Absent when neither exists yet.
True when credits_charged is the dispatch estimate rather than a settled charge.
In = a caller input; out = the platform.
Wall-clock seconds from submission to completion.
Opaque event id (sevt_…).
Model id that produced the outputs.
Generated assets.
A reference to a generated asset ready for delivery.
object
Durable artifact identifier for this output.
Duration in seconds, for video outputs.
Pixel height, for image and video outputs.
Backend job identifier that produced this output.
Per-layer semantics, on the outputs of a layering job: run.completed, job.completed, turn outputs, and the run and job reads. Outputs are ordered front to back; the last is the background.
object
Edge treatment of the layer's transparency — soft (hair/fur/glass), hard (solid edges), or none (the opaque background).
Placement of this layer's pixels within the composite canvas. Absent only when the output's dimensions could not be resolved.
object
Height of the full composite canvas the layers reassemble into.
Width of the full composite canvas the layers reassemble into.
Pixel height of the returned layer image.
Pixel width of the returned layer image.
Left offset of this layer's pixels within the composite canvas.
Top offset of this layer's pixels within the composite canvas.
Whether the layer was planned as typeset text (a headline, caption, or label) rather than an image element. Absent when not reported for this output.
Complete-element caption for the layer's content.
Layer position, front-to-back; the last layer is the background.
Short (1-2 word) layer name.
The text read off a contains_text layer, so it can be re-typeset as live text inside bounds. Absent when the layer holds no text, or its lettering could not be read or is a logo / wordmark. Final whenever the job is. A layering job is not reported finished until reading its text has finished or timed out.
object
The text as shown, preserving capitalization, with a line break between lines.
True when the lettering is ornamental (outlines, patterned fills, bevels, drop shadows), so plain typeset text will not reproduce its look.
Described typeface traits. Absent when they could not be read.
object
Letterform style.
Up to three Google Fonts family names that resemble the lettering, closest first. Empty when none of the offered families fit.
Whether the letters are slanted or cursive.
The font in your font catalog that the lettering matches, so you can re-set the text in it. Absent when no catalog font matches closely enough, or matching is not enabled. The image itself is not rendered in this font.
object
Typed ref of the matched face (one weight and style), font_face:
Typed ref of the matched font family, font_family:
Name of the matched font family.
Style of the matched face.
CSS font weight of the matched face, e.g. 400 or 700.
Stroke weight.
Letter width for its height.
Exact MIME type of the asset, e.g. image/png. Narrower than type, which is a coarse bucket.
Model id that produced this output.
Size of the asset in bytes.
Presigned URL to a thumbnail variant.
Asset media type.
Presigned URL to the asset.
Pixel width, for image and video outputs.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A GPU job failed. The server will continue the agent turn so it can inform the user.
object
Sub-agent name, present when the event originates from a sub-agent.
Bucket derived from failure_code — what the caller can do about it.
ISO-8601 time the event was recorded.
Credits charged for the failed job. Zero unless it settled.
In = a caller input; out = the platform.
Error-taxonomy code, e.g. USER.MODERATION.UNSAFE_CONTENT.
Opaque event id (sevt_…).
Model id the job dispatched to.
Moderation verdict detail. Present only on moderation failures.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
Whether resubmitting the same job could succeed.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A long-running GPU generation job was submitted. The agent is waiting for it to complete.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Pre-dispatch credit estimate for this job.
Rough estimate in seconds.
Opaque event id (sevt_…).
Tool invocation that submitted this job; matches agent.tool_use / agent.tool_result.
Backend job identifier. A continuation session.status_running names it in job_ids when its completion resumes the session.
Model id the job dispatched to.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Job state at submission. Always queued today.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The session plan artifact was mutated. Carries the new revision and the mutator — fetch the snapshot via GET /v1/sessions/{id}, it is not inlined.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Tool/stage that performed the mutation, e.g. plan_storyboard.
Human-readable one-liner describing the mutation.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
New artifact revision after this mutation.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A run reached a terminal state. No further event carries this run_id.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Set when state is failed: the error code the run failed with, as GET /v1/sessions/{session_id}/runs/{run_id} reports it.
Opaque event id (sevt_…).
Assets this run produced.
A reference to a generated asset ready for delivery.
object
Durable artifact identifier for this output.
Duration in seconds, for video outputs.
Pixel height, for image and video outputs.
Backend job identifier that produced this output.
Per-layer semantics, on the outputs of a layering job: run.completed, job.completed, turn outputs, and the run and job reads. Outputs are ordered front to back; the last is the background.
object
Edge treatment of the layer's transparency — soft (hair/fur/glass), hard (solid edges), or none (the opaque background).
Placement of this layer's pixels within the composite canvas. Absent only when the output's dimensions could not be resolved.
object
Height of the full composite canvas the layers reassemble into.
Width of the full composite canvas the layers reassemble into.
Pixel height of the returned layer image.
Pixel width of the returned layer image.
Left offset of this layer's pixels within the composite canvas.
Top offset of this layer's pixels within the composite canvas.
Whether the layer was planned as typeset text (a headline, caption, or label) rather than an image element. Absent when not reported for this output.
Complete-element caption for the layer's content.
Layer position, front-to-back; the last layer is the background.
Short (1-2 word) layer name.
The text read off a contains_text layer, so it can be re-typeset as live text inside bounds. Absent when the layer holds no text, or its lettering could not be read or is a logo / wordmark. Final whenever the job is. A layering job is not reported finished until reading its text has finished or timed out.
object
The text as shown, preserving capitalization, with a line break between lines.
True when the lettering is ornamental (outlines, patterned fills, bevels, drop shadows), so plain typeset text will not reproduce its look.
Described typeface traits. Absent when they could not be read.
object
Letterform style.
Up to three Google Fonts family names that resemble the lettering, closest first. Empty when none of the offered families fit.
Whether the letters are slanted or cursive.
The font in your font catalog that the lettering matches, so you can re-set the text in it. Absent when no catalog font matches closely enough, or matching is not enabled. The image itself is not rendered in this font.
object
Typed ref of the matched face (one weight and style), font_face:
Typed ref of the matched font family, font_family:
Name of the matched font family.
Style of the matched face.
CSS font weight of the matched face, e.g. 400 or 700.
Stroke weight.
Letter width for its height.
Exact MIME type of the asset, e.g. image/png. Narrower than type, which is a coarse bucket.
Model id that produced this output.
Size of the asset in bytes.
Presigned URL to a thumbnail variant.
Asset media type.
Presigned URL to the asset.
Pixel width, for image and video outputs.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
Typed named-operation result, present only after successful completion.
object
The run this event belongs to.
Per-feed ordinal.
Set when this run settled together with another run: the run_id of that run, which holds its work and results.
Which terminal state the run reached.
One-line account of what the run did.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A run began inside this session. Every later event carrying this run_id belongs to it.
object
Sub-agent name, present when the event originates from a sub-agent.
Capability slug, for a capability run.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
What kind of work this run is.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The session is approaching its credit budget.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
Remaining credit balance at the time of this warning.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
Luma changed what the session's agent holds since the session was created or since the last such event: a platform tool, platform skill or app tool was switched off, or came back. Sent as the first turn that runs with the change starts. Each list is the session's whole answer now, the same as effective on GET /v1/sessions/{id}.
object
Sub-agent name, present when the event originates from a sub-agent.
The workflow-app tools the agent holds now.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
The platform skills on the agent's menu now, by slug.
The platform tools the agent holds now, by name.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A top-up quote the run needs accepted before it can continue; until then the run is paused at its current cap. The session's pending names it by quote_id.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
RFC 3339 UTC instant after which the quote can no longer be accepted. Absent means it lives as long as the session.
Credits this quote would add to the run, held on accept.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
Identifier of the offered quote, echoed back on accept.
Why more money is being asked for.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
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.
The session is summarizing its older history so it fits the model's context window; the turn's model call waits until it finishes. A start is followed by complete or failed. On failed the turn continues with the full history. Recorded, so a client that connects or resumes mid-wait sees the start, and its created_at says when the wait began. A start with neither after 1200 seconds belongs to a worker that died and should be read as failed. Informational only — no client action.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Where the compaction is: started, finished with a stored summary, or abandoned.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A turn failed. retry_status says what happens next.
object
Registered SESSION.* error code.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
Retrying — the server is retrying; exhausted — this turn is over, a new input may succeed; terminal — the session cannot continue.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
An input or event the server accepted could not be processed. input_seq names the recorded input it answers.
object
ISO-8601 time the event was recorded.
Human-readable explanation of the failure.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
The seq of the recorded input this failure answers.
Identifier of the event that failed delivery.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The session stopped and is waiting. requires_action lists every pending item; a partial answer re-emits it with the remainder.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Why the session went idle. pending is present only for requires_action; code, message and retryable only for error.
object
Error only: the registered session error code.
Error only: a message safe to show the user.
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.
Error only: whether sending the request again could succeed. The session stays open.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The session started working: a turn, or a continuation after server-side jobs landed.
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.
True when the server resumed after its own jobs finished.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Continuation only: the jobs whose completion resumed the session.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The session ended. No further events follow.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
The previous attempt at this turn stopped before it ended, and the server is running the turn again from the same history. Comes before the retry's session.status_running. Every invocation_id in abandoned_invocation_ids belongs to the stopped attempt and is never answerable: drop any card or spinner for it. The retry may ask the same tool again under a new invocation_id. Informational only — no client action.
object
Tool calls the stopped attempt started that got no result. Empty when it started none.
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
worker_lost: the process running the attempt died. attempt_failed: the attempt stopped, by an error or a worker shutdown, and the server retries it.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
What the turn that just ended consumed and produced. Always immediately precedes session.status_idle.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
One generation job the turn dispatched or landed, with its state at turn end.
object
Job state at the moment the turn ended.
A reference to a generated asset ready for delivery.
object
Durable artifact identifier for this output.
Duration in seconds, for video outputs.
Pixel height, for image and video outputs.
Backend job identifier that produced this output.
Per-layer semantics, on the outputs of a layering job: run.completed, job.completed, turn outputs, and the run and job reads. Outputs are ordered front to back; the last is the background.
object
Edge treatment of the layer's transparency — soft (hair/fur/glass), hard (solid edges), or none (the opaque background).
Placement of this layer's pixels within the composite canvas. Absent only when the output's dimensions could not be resolved.
object
Height of the full composite canvas the layers reassemble into.
Width of the full composite canvas the layers reassemble into.
Pixel height of the returned layer image.
Pixel width of the returned layer image.
Left offset of this layer's pixels within the composite canvas.
Top offset of this layer's pixels within the composite canvas.
Whether the layer was planned as typeset text (a headline, caption, or label) rather than an image element. Absent when not reported for this output.
Complete-element caption for the layer's content.
Layer position, front-to-back; the last layer is the background.
Short (1-2 word) layer name.
The text read off a contains_text layer, so it can be re-typeset as live text inside bounds. Absent when the layer holds no text, or its lettering could not be read or is a logo / wordmark. Final whenever the job is. A layering job is not reported finished until reading its text has finished or timed out.
object
The text as shown, preserving capitalization, with a line break between lines.
True when the lettering is ornamental (outlines, patterned fills, bevels, drop shadows), so plain typeset text will not reproduce its look.
Described typeface traits. Absent when they could not be read.
object
Letterform style.
Up to three Google Fonts family names that resemble the lettering, closest first. Empty when none of the offered families fit.
Whether the letters are slanted or cursive.
The font in your font catalog that the lettering matches, so you can re-set the text in it. Absent when no catalog font matches closely enough, or matching is not enabled. The image itself is not rendered in this font.
object
Typed ref of the matched face (one weight and style), font_face:
Typed ref of the matched font family, font_family:
Name of the matched font family.
Style of the matched face.
CSS font weight of the matched face, e.g. 400 or 700.
Stroke weight.
Letter width for its height.
Exact MIME type of the asset, e.g. image/png. Narrower than type, which is a coarse bucket.
Model id that produced this output.
Size of the asset in bytes.
Presigned URL to a thumbnail variant.
Asset media type.
Presigned URL to the asset.
Pixel width, for image and video outputs.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
Token and credit consumption for a single turn.
object
Completion tokens produced.
Luma credits charged. Present when billing is enabled.
Prompt tokens consumed.
An orchestration stage reached a terminal state.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Terminal stage status: 'completed' | 'failed'.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
An orchestration stage began — its tool dispatched one or more jobs.
object
Sub-agent name, present when the event originates from a sub-agent.
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Backend job identifiers dispatched for this stage.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Stage name, e.g. render_keyframes.
Stage status, e.g. 'running'.
Catalog tool that drives this stage.
True when the recorded event exceeded the size cap and only its identity fields were kept. Refetch the resource it names.
A message from the caller; opens or joins a run.
object
Run this capability on the message. The result's run_id is the capability run.
object
The capability's slug from GET /v1/apps, or 'slug@version' to pin the release.
Typed fields matching the capability's intake input_schema. Absent, the message content is the brief.
object
Extra standing instructions for the capability's own work.
Things of your team for the session's agent to follow on this message and the work it orders, each by the id its own list prints: brand_kit:
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
Stop the current turn, or with target_run_id that one run. tree also stops descendant sessions.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
The run to cancel: a brief, a generate run or a capability run on this session. Absent, the current turn is interrupted.
The result of a custom tool the session asked the caller to run.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Present only on an answer the platform recorded because the webhook tool failed; a caller cannot send it.
object
WEBHOOK.NON_2XX, WEBHOOK.NOT_JSON, WEBHOOK.TIMEOUT, WEBHOOK.TOO_LARGE, WEBHOOK.DESTINATION_REFUSED, WEBHOOK.INVALID_REPLY, WEBHOOK.DISPATCH_FAILED or TOOL.DEADLINE_EXCEEDED.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
The caller's answer to a review gate.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
object
One of the app's typed commands, run against the session outside a turn.
object
The command body in the app's command schema. Unless the body's own schema declares them, expected_revision must match the plan artifact's revision before the command runs, and it and operation_id are left out of the recorded input and its idempotency comparison.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
The command the app authorizes the call as.
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
The run this event belongs to.
Per-feed ordinal.
The caller's answer to a billing offer the session's pending names by quote_id. Names only the quote, never an amount: the server holds the offer's frozen terms.
object
ISO-8601 time the event was recorded.
In = a caller input; out = the platform.
Opaque event id (sevt_…).
Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.
object
App only: the capability's slug.
App only: the capability run the event belongs to: a run ref (run:<id>) when the session spells refs typed, else the bare run id.
Identifier of the offered quote, echoed back on accept.
The run this event belongs to.
Per-feed ordinal.
True when events after next_after_seq exist.
Pass as after_seq to read the next page.
Example
{ "data": [ { "direction": "in", "producer": { "kind": "root" }, "retry_status": "retrying", "source": "slug", "stop_reason": { "pending": [ { "answer_type": "user.tool_result", "kind": "custom_tool", "offer": "finals" } ], "type": "end_turn" }, "truncated": true } ]}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}