Skip to content
Agents
Events

Session Events

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

session_id
required
Session Id
string
after_seq
Any of:
string

JSON page: return events with seq greater than this. Default 0.

limit
Any of:
string

JSON page: page size, 1-500. Default 100.

types
Any of:
string

JSON page: comma-separated wire event types to include.

run_id
Any of:
string

JSON page: only this run's events.

One page of the session's event log, in seq order.

Media typeapplication/json
SessionEventListResponse

One page of a session's event log, in seq order.

object
data
required
Data
Array
Any of:
TruncatedSessionEvent

An over-cap recorded event: the envelope, its identity fields, and truncated.

object
abandoned_invocation_ids
Abandoned Invocation Ids

Tool calls the stopped attempt started that got no result. Empty when it started none.

Array<string>
agent
Agent
string
artifact_rsid
Artifact Rsid

Durable id of the generated artifact.

string
asset_id
Asset Id
string
attachment_id
Attachment Id

The attachment id returned by POST /v1/attachments.

string
code
Code

Registered SESSION.* error code.

string
continuation
Continuation

True when the server resumed after its own jobs finished.

boolean
created_at
required
Created At

ISO-8601 time the event was recorded.

string
credits_remaining
Credits Remaining

Remaining credit balance at the time of this warning.

integer
direction
required
Direction

In = a caller input; out = the platform.

string
Allowed values: in out
hold_credits
Hold Credits

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

integer
id
required
Id

Opaque event id (sevt_…).

string
input_seq
Input Seq

The seq of the recorded input this failure answers.

integer
interaction
Interaction

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
key
additional properties
any
invocation_id
Invocation Id
string
is_error
Is Error
boolean
job_id
Job Id
string
kind
Kind
string
mutated_by
Mutated By

Tool/stage that performed the mutation, e.g. plan_storyboard.

string
operation
Operation

The command the app authorizes the call as.

string
pending_event_id
Pending Event Id

Identifier of the event that failed delivery.

string
producer
EventProducer

Who produced an outbound event: the session itself, or a capability working for it. Absent on inputs.

object
app
App

App only: the capability's slug.

string
kind
required
Kind
string
Allowed values: root app
run_id
Run Id

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.

string
quote_id
Quote Id

Identifier of the offered quote, echoed back on accept.

string
reason
Reason
string
retry_status
Retry Status

Retrying — the server is retrying; exhausted — this turn is over, a new input may succeed; terminal — the session cannot continue.

string
Allowed values: retrying exhausted terminal
revision
Revision

New artifact revision after this mutation.

integer
run_id
Run Id

The run this event belongs to.

string
seq
required
Seq

Per-feed ordinal.

integer
skill_name
Skill Name

Skill name (durable slug, inline playbook name, or the name of a partner skill the session attached).

string
source
Source

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.

string
Allowed values: slug inline client
stage
Stage
string
state
State
string
status
Status
string
stop_reason
StopReason

Why the session went idle. pending is present only for requires_action; code, message and retryable only for error.

object
code
Code

Error only: the registered session error code.

string
message
Message

Error only: a message safe to show the user.

string
pending
Pending
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
retryable
Retryable

Error only: whether sending the request again could succeed. The session stays open.

boolean
type
required
Type
string
Allowed values: end_turn requires_action budget_reached interrupted error
tool
Tool
string
tree
Tree
boolean
truncated
required
Truncated

Always true: only identity fields were kept.

boolean
turn_id
Turn Id
string
type
required
Type

The wire type.

string
has_more
required
Has More

True when events after next_after_seq exist.

boolean
next_after_seq
required
Next After Seq

Pass as after_seq to read the next page.

integer
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

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