On this page
List session events
Lists a session's events in sequence order.
Lists a session's events in sequence order. To follow a session, call again with the filter sequence > N, N the last sequence read; wait holds the call open until a newer event is appended or the wait ends.
- Path
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/session_events - Scope
agents:sessions - Effect
read— nothing is written. - Collection session_events
- Query
page_size,page_token,filter,wait - Pagination the answer carries
session_eventsand, when there is more,next_page_token
Request
| Field | Type | What it is |
|---|---|---|
parent | string | The session to list in. Required. |
page_size | int32 | At most this many; default 50, clamped to 1000. |
page_token | string | next_page_token of the previous page. |
filter | string | AIP-160 filter, limited to type and sequence; for example sequence > 42. |
wait | duration | When no event matches the filter, wait up to this long for one, at most 60s; unset answers at once. |
Response
| Field | Type | What it is |
|---|---|---|
session_events | SessionEvent[] | The page. |
next_page_token | string | The token of the next page; empty on the last page. |
SessionEvent
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session}/session_events/{session_event}. |
uid | string | sevt_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
sequence | int64 | The position in the session's log, from 1, with no gaps. Output only. |
type | SessionEventType | What the event is. Output only. One of user_message, steer, agent_message, tool_call, tool_result, approval_requested, approval_decided, status, compaction, thought, file_change, response, error, usage, sandbox, wait_changed, wait_continuation. |
turn | int64 | The turn it belongs to, from 1; 0 for an event outside a turn. Output only. |
step | int64 | The step within the turn, from 1, assigned by the runtime; 0 for an event that is not a step. Output only. |
create_time | timestamp | When it was appended. Output only. |
usage | StepUsage | Observed accounting for this step; absent values are unknown, never zero. Output only. |
step_key | string | Stable runtime-assigned effect key, independent of invocation attempts. Output only. |
message | Message | For USER_MESSAGE, STEER and AGENT_MESSAGE. One of the payload group. |
tool_call | ToolCall | For TOOL_CALL. One of the payload group. |
tool_result | ToolResult | For TOOL_RESULT. One of the payload group. |
approval | Approval | For APPROVAL_REQUESTED and APPROVAL_DECIDED. One of the payload group. |
status_change | StatusChange | For STATUS. One of the payload group. |
thought | Message | For THOUGHT: a reasoning summary, never private model reasoning. One of the payload group. |
file_change | FileChange | For FILE_CHANGE. One of the payload group. |
response | TurnResult | For RESPONSE: the completed turn's answer and usage. One of the payload group. |
error | ErrorEvent | For ERROR. One of the payload group. |
sandbox | SandboxActivity | For SANDBOX: authoritative allocation/release history, including replacements. One of the payload group. |
wait | AgentSessionWait | For WAIT_CHANGED: a durable wait fact, without execution authority. One of the payload group. |
wait_continuation | SessionWaitContinuation | For WAIT_CONTINUATION: ready owners consumed by exact turn admission. One of the payload group. |
ResourceMeta
| Field | Type | What it is |
|---|---|---|
generation | int64 | Increases by one on every change to spec. Output only. |
etag | string | Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only. |
create_time | timestamp | When the Resource was created. Output only. |
update_time | timestamp | When the Resource last changed. Output only. |
delete_time | timestamp | Set while the Resource is being deleted. Output only. |
labels | map<string, string> | Caller-writable, indexed labels (AIP-122 label rules). |
annotations | map<string, string> | Caller-writable, unindexed annotations. |
display_name | string | Caller-writable human-readable name. |
creator | string | The principal that created the Resource. Output only. |
StepUsage
| Field | Type | What it is |
|---|---|---|
input_tokens | uint64 | Uncached input tokens the step was charged for; absent when unknown. Output only. |
cached_tokens | uint64 | Input tokens served from the provider cache; absent when unknown. Output only. |
output_tokens | uint64 | Output tokens; absent when unknown. Output only. |
cost_usd | string | The exact decimal USD charge the gateway reported; absent when unknown. Output only. |
model | string | The catalog id the step ran on; empty for a step with no inference. Output only. |
kind | string | model, tool, compaction or subcall. Output only. |
first_delta_time | timestamp | For a model step: when the runtime received the stream's first non-empty assistant text or tool-call delta (not a role-only or empty chunk), on the runtime's clock, from the attempt that produced the recorded step. Output only. |
Message
| Field | Type | What it is |
|---|---|---|
parts | ContentPart[] | The content, in order; 1 to 64 parts. Required. |
ToolCall
| Field | Type | What it is |
|---|---|---|
id | string | The call's id within the session, (turn, step) based. Output only. |
tool | string | The tool name. Output only. |
input | struct | The input, as the model sent it. Output only. |
model_call_id | string | The model's own id for the call, as sent; never used as a key. Output only. |
client | bool | Whether the client must execute this pending call. Calls rejected before dispatch remain in history with this false and a corresponding ToolResult. Output only. |
deadline | timestamp | The client call's fixed deadline. A reconnecting client never starts a call after this time; retries retain the original deadline and call id. Output only. |
ToolResult
| Field | Type | What it is |
|---|---|---|
call_id | string | The ToolCall's id. Output only. |
output | value | The output. Output only. |
error | bool | Whether the call failed; output then holds the error. Output only. |
duration | duration | How long the call took. Output only. |
Approval
| Field | Type | What it is |
|---|---|---|
call_id | string | The ToolCall's id. Output only. |
decision | ApprovalDecision | The answer, once given; unset while it waits. Output only. One of approve, reject. |
remember | bool | Whether the answer covers later calls of the same tool in this session ("always allow"). Output only. |
principal | string | Who answered. Output only. |
reason | string | The reason given, if any. Output only. |
StatusChange
| Field | Type | What it is |
|---|---|---|
state | SessionState | The state after the change. Output only. One of idle, running, awaiting_approval, awaiting_client, failed, archived. |
reason | string | Why, for FAILED and INTERRUPTED: a registry error code and message. Output only. |
FileChange
| Field | Type | What it is |
|---|---|---|
path | string | The path relative to the session's repository root. Output only. |
change | string | added, modified, deleted, renamed or copied. Output only. |
added | int64 | Lines added, when reported by the harness. Output only. |
removed | int64 | Lines removed, when reported by the harness. Output only. |
old_path | string | The previous path, for a rename or copy. Output only. |
source | string | edit for an incremental edit or final for the turn's final diff. Output only. |
TurnResult
| Field | Type | What it is |
|---|---|---|
text | string | The final response's text. Output only. |
is_error | bool | Whether the turn ended with an error. Output only. |
usage | TurnTokenUsage | Model token usage reported by the harness. Output only. |
cost_micros | int64 | The reported cost, in micro-USD. Output only. |
duration | duration | How long the turn ran. Output only. |
first_delta_time | timestamp | The first non-empty assistant text or tool-call delta of the turn: the earliest first_delta_time of its recorded model steps. Output only. |
ErrorEvent
| Field | Type | What it is |
|---|---|---|
kind | string | The registry error code or harness error kind. Output only. |
message | string | A safe error description. Output only. |
SandboxActivity
| Field | Type | What it is |
|---|---|---|
lease | string | The lease's resource name. Output only. |
state | string | allocated or released (the release was read back as ENDED). Output only. |
sandbox_seconds | string | On released: exact decimal seconds from allocation to release. Output only. |
AgentSessionWait
| Field | Type | What it is |
|---|---|---|
name | string | Exact name; the final segment is the conserved wait UUID. |
uid | string | Immutable platform Resource UID. Output only. |
meta | ResourceMeta | Standard metadata. Output only. |
goal | string | Optional exact Goal in this Session, never a current-Goal selector. |
type | string | time or signal. Other producer types require their own admitted adapter. Required. |
reference | string | Exact source reference for a signal; empty for a timer. |
deadline | timestamp | Actual future due time; required only for a timer. |
resume_prompt | string | What to do after observing this wait's evidence, at most 16 KiB. Required. |
state | string | active, ready, resolved or cancelled. Ready still requires turn admission. Output only. |
evidence | struct | Original bounded observed evidence, retained through delivery and restart. Output only. |
resumed_turn | int64 | The only turn that consumed this wait; unset until resolved. Output only. |
create_time | timestamp | Creation time. Output only. |
update_time | timestamp | Last state change time. Output only. |
SessionWaitContinuation
| Field | Type | What it is |
|---|---|---|
waits | AgentSessionWait[] | Conserved wait snapshots and observed evidence for this exact turn. Output only. |
ContentPart
| Field | Type | What it is |
|---|---|---|
text | string | Text. One of the part group. |
file | FileRef | A file, by Sylphx Data object URL or an https URL. One of the part group. |
TurnTokenUsage
| Field | Type | What it is |
|---|---|---|
input_tokens | int64 | Input tokens. Output only. |
output_tokens | int64 | Output tokens. Output only. |
cache_read_tokens | int64 | Input tokens read from the model's cache. Output only. |
cache_write_tokens | int64 | Input tokens written to the model's cache. Output only. |
Errors
RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.INVALID_FIELD— A field failed validation.PAGE_TOKEN_MISMATCH— A page token was reused with different parameters.
Every error arrives in the body Errors describes.
Examples
curl "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session/session_events" \
-H "Authorization: Bearer $SYLPHX_API_KEY"