Session events

Every modeled session event, with JSON examples for platform, harness, and streaming consumers.

Read session records through List records or receive them in a live stream's records_append frames. Open an event to see its example JSON and detailed field specification. Events are grouped by producer and ordered roughly from startup through execution to completion and recovery.

Examples are illustrative, independent messages, not a consecutive transcript. Optional native fields vary by harness version. Platform and transport types are listed in full; native harnesses can also send additional types through unknown records.

Platform: session, sandbox, inbox, and turn events.
Claude Code: native messages and turn results.
Codex: native app-server notifications.
WebSocket frames: delivery, live output, and connection state.
Historical formats: records retained from older sessions.

For the important transitions and how turns, idle periods, and closure relate, start with Lifecycle.

Read an event

Field	How to use it
`kind`	Select the typed record variant: `platform`, `claude_code`, `codex_app_server`, `claude_sdk`, `codex`, or `unknown`.
`source`	Identify the producer: `lifecycle`, `claude_code`, or `codex`.
`record_format`	Select the payload version; existing history retains its original format.
`record_type`	Identify the event within its format.
`payload`	Read the platform fields or the unchanged native message.
`feed_seq`	Order records within a session and resume the stream after this position.
`stream_seq`	Order records within an execution.
`session_execution_id`	Correlate records with an execution; null for events before an execution exists.
`agent_turn_id`	Correlate records with a turn when one applies.
`session_message_id`	Correlate inbox events and native user echoes so a message can render once.

Use kind and record_type to narrow platform records. For native records, narrow kind first, then payload.type (Claude and historical Codex) or payload.method (current Codex). Native payloads can have their own kind field, such as "push" in a Claude Git notification; it is event data, not the envelope's record variant. Claude rate limits are the exception: record_type is rate_limit, while payload.type is rate_limit_event.

The field specifications below come from the SDK schema. Required means the field must be present; null in its type means its value can be null. Expand nested fields to inspect their properties and variants. Required fields within a variant apply when that variant is used. Examples show one possible payload; optional native fields may be absent.

Both SDKs expose SessionRecord and StreamFrame:

from ellipsis.models import SessionRecord
from ellipsis.frames import StreamFrame

import type { SessionRecord, StreamFrame } from '@ellipsis-dev/sdk';

Platform

These records use kind: "platform", source: "lifecycle", and record_format: "ellipsis_lifecycle@1". Events describe individual changes; not every session produces every type.

session_scheduledThe session was created and queued for execution.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_scheduled",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": null,
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 1,
  "stream_seq": 0,
  "payload": {
    "source": "api",
    "config_name": null,
    "config_commit_sha": null
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_scheduled".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

sourcestringRequired
config_commit_shastring | nullOptional
config_namestring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

message_receivedA prompt, follow-up, or event-generated message entered the inbox; closes_session marks a final message.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_received",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": null,
  "agent_turn_id": null,
  "session_message_id": "message_example",
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "message_id": "message_example",
    "body": "Run the tests and report failures.",
    "author": "priya-shah",
    "sender_attribution_type": "github_user",
    "sender_attribution_id": "12345",
    "closes_session": false
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "message_received".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

authorstring | nullOptional
bodystringRequired
closes_sessionbooleanOptional
message_idstringRequired
sender_attribution_idstring | nullOptional
sender_attribution_typestring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

session_startingAn execution is starting after its initial checks passed; wake_index distinguishes a fresh start from a later wake.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_starting",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "attempt": 0,
    "wake_index": 0
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_starting".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

attemptintegerRequired
wake_indexintegerRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

session_cancelledAn initial check cancelled execution before a sandbox was provisioned, with a reason you can display.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_cancelled",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": null,
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "reason": "The session budget has been exhausted."
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_cancelled".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

reasonstringRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

sandbox_startingSandbox preparation began for the listed repositories.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_starting",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "repositories": [
      "your-org/api-repo"
    ]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "sandbox_starting".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

repositoriesarray<string>Required

Fields and variants

[]string

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

sandbox_phaseA sandbox preparation phase started, completed, or failed, with optional timing and details.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_phase",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "phase": "clone",
    "status": "completed",
    "step": null,
    "duration_ms": 2400,
    "detail": null
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "sandbox_phase".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

detailobject | nullOptional: Additional properties are allowed.
duration_msinteger | nullOptional
phasestringRequired
statusstringRequired
stepstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

sandbox_outputA chunk of stdout or stderr arrived from sandbox preparation or lifecycle scripts.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_output",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "phase": "clone",
    "step": "your-org/api-repo",
    "stream": "stdout",
    "chunk": 0,
    "lines": [
      "Cloning into 'api-repo'..."
    ]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "sandbox_output".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

chunkintegerRequired

linesarray<string>Required

Fields and variants

[]string

phasestringRequired

stepstring | nullOptional

streamstringOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

sandbox_readyThe sandbox is ready to launch the harness, with cache and preparation timing information.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "sandbox_ready",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "repositories": [
      "your-org/api-repo"
    ],
    "cache_tier": "exact",
    "phase_timings": {
      "clone": 2.4
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "sandbox_ready".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

cache_tierstring | nullOptional

phase_timingsobjectOptional

Additional properties are allowed.

Fields and variants

[key]number

repositoriesarray<string>Required

Fields and variants

[]string

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

session_resumedA later execution successfully restored the existing native conversation.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_resumed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "wake_index": 1
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_resumed".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

wake_indexintegerRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn_startedA platform turn began.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "turn_started".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

turn_idstringRequired
turn_indexintegerRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

message_deliveredAn inbox message was delivered to the identified turn.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_delivered",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": "message_example",
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "message_id": "message_example",
    "turn_id": "turn_example"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "message_delivered".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

message_idstringRequired
turn_idstringRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn_completedA platform turn completed successfully.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0,
    "duration_ms": 4200
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "turn_completed".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

duration_msinteger | nullOptional
turn_idstringRequired
turn_indexintegerRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn_failedA platform turn ended unsuccessfully; this event alone does not mean its messages will be requeued.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "turn_failed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "turn_id": "turn_example",
    "turn_index": 0
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "turn_failed".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

turn_idstringRequired
turn_indexintegerRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

message_requeuedA previously delivered message returned to the inbox for redelivery during failure recovery.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "message_requeued",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": "message_example",
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "message_id": "message_example",
    "turn_id": "turn_example"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "message_requeued".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

message_idstringRequired
turn_idstringRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

session_retryingExecution will retry after a temporary infrastructure failure before the agent acted.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_retrying",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": null,
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "reason": "The sandbox could not be started. Retrying.",
    "attempt": 1
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_retrying".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

attemptintegerRequired
reasonstringRequired

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

outbox_collectedA code-review session collected its review output, including raw files, parsed findings, and parsing errors.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "outbox_collected",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "raw": {},
    "findings": [],
    "parse_errors": [],
    "parser_version": "1"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "outbox_collected".

payloadobjectRequired

Additional properties are allowed.

Fields and variants

findingsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

parse_errorsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

parser_versionstringRequired

rawobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

session_idleThe execution loop ended and the persistent conversation is parked until another message arrives.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_idle",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {},
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_idle".

payloadobjectRequired

Additional properties are allowed.

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

session_closedThe conversation closed permanently after its final turn or the end of a one-shot session.

Link to this event

Example JSON

{
  "kind": "platform",
  "source": "lifecycle",
  "record_format": "ellipsis_lifecycle@1",
  "record_type": "session_closed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {},
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "platform".

sourcestringRequired

Must be "lifecycle".

record_formatstringRequired

Must be "ellipsis_lifecycle@1".

record_typestringRequired

Must be "session_closed".

payloadobjectRequired

Additional properties are allowed.

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

sandbox_phase.status currently uses started, completed, and failed. Treat phase names, steps, and statuses as open strings. A sandbox can emit many phase and output records.

session_idle marks a parked conversation, not every pause between turns. Session success, failure, and stop status arrive through the session frame; there are no separate session_completed, session_failed, or session_stopped platform records.

Claude Code

Current Claude records use kind: "claude_code", source: "claude_code", and record_format: "claude_jsonl@1". A native result ends a harness turn, not necessarily the whole session.

systemReports harness metadata, including initialization, status, compaction, hooks, and background-task activity through subtype.

Link to this event

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "system",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "system",
    "subtype": "init",
    "model": "claude-sonnet-5",
    "tools": [
      "Bash",
      "Read"
    ],
    "cwd": "/workspace",
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "system".
session_idstring | nullOptional
subtypestringRequired
uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

systemReports a Git state change through subtype: vcs_state_changed; payload.kind identifies the operation, such as a push.

Link to this event

This notification is part of the current turn's activity. It does not complete or fail the turn. Its native kind, cwd, and other fields are preserved in payload; record_type remains system.

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "system",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "system",
    "subtype": "vcs_state_changed",
    "kind": "push",
    "cwd": "/workspace",
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "system".
session_idstring | nullOptional
subtypestringRequired
uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

userCarries a user-message echo or tool results supplied back to Claude; this example is a tool result.

Link to this event

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "user",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "user",
    "message": {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "tool_example",
          "content": "12 passed",
          "is_error": false
        }
      ]
    },
    "parent_tool_use_id": null,
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "user".

isReplayboolean | nullOptional

messageobjectRequired

Additional properties are allowed.

Fields and variants

contentstring | array<object>Required

Matches at least one variant below.

Fields and variants

variant 1string

variant 2array<object>

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "text".
textstringRequired

type = "thinking"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "thinking".
signaturestringRequired
thinkingstringRequired

type = "tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "tool_result".

contentstring | array<object> | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2array<object>

Fields and variants

[]object: Additional properties are allowed.

is_errorboolean | nullOptional

tool_use_idstringRequired

type = "server_tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "server_tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_result".
contentobjectOptional: Additional properties are allowed.
tool_use_idstringRequired

rolestringRequired

Must be "user".

parent_tool_use_idstring | nullOptional

session_idstring | nullOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

assistantCarries completed assistant content, including text, thinking, and tool calls.

Link to this event

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "assistant",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "assistant",
    "message": {
      "type": "message",
      "role": "assistant",
      "id": "message_native",
      "model": "claude-sonnet-5",
      "content": [
        {
          "type": "text",
          "text": "I will run the tests."
        },
        {
          "type": "tool_use",
          "id": "tool_example",
          "name": "Bash",
          "input": {
            "command": "pytest -q"
          }
        }
      ],
      "usage": {
        "input_tokens": 1200,
        "output_tokens": 80,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      "stop_reason": "tool_use"
    },
    "parent_tool_use_id": null,
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": [
    "Bash"
  ],
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": null,
  "duration": null,
  "model": "claude-sonnet-5",
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "assistant".

errorstring | nullOptional

messageobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "message".

contentarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "text".
textstringRequired

type = "thinking"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "thinking".
signaturestringRequired
thinkingstringRequired

type = "tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "tool_result".

contentstring | array<object> | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2array<object>

Fields and variants

[]object: Additional properties are allowed.

is_errorboolean | nullOptional

tool_use_idstringRequired

type = "server_tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "server_tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_result".
contentobjectOptional: Additional properties are allowed.
tool_use_idstringRequired

idstring | nullOptional

modelstringRequired

rolestringRequired

Must be "assistant".

stop_reasonstring | nullOptional

stop_sequencestring | nullOptional

usageobject | nullOptional

Additional properties are allowed.

Fields and variants

cache_creationobject | nullOptional: Additional properties are allowed.
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
input_tokensintegerOptional
output_tokensintegerOptional

parent_tool_use_idstring | nullOptional

session_idstring | nullOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

rate_limitReports rate-limit status and reset information; the native payload names the event rate_limit_event.

Link to this event

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "rate_limit",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "rate_limit_event",
    "rate_limit_info": {
      "status": "allowed",
      "rateLimitType": "five_hour",
      "utilization": 0.25,
      "resetsAt": 1789066800
    },
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "rate_limit_event".

rate_limit_infoobjectRequired

Additional properties are allowed.

Fields and variants

overageDisabledReasonstring | nullOptional
overageResetsAtinteger | nullOptional
overageStatusstring | nullOptional
rateLimitTypestring | nullOptional
resetsAtinteger | nullOptional
statusstringRequired
utilizationnumber | nullOptional

session_idstring | nullOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

resultReports a harness turn outcome with its output, elapsed time, usage, and reported cost.

Link to this event

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "result",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "result",
    "subtype": "success",
    "is_error": false,
    "num_turns": 1,
    "duration_ms": 4200,
    "duration_api_ms": 3100,
    "result": "All 12 tests passed.",
    "total_cost_usd": 0.01,
    "usage": {
      "input_tokens": 1200,
      "output_tokens": 80,
      "cache_read_input_tokens": 0,
      "cache_creation_input_tokens": 0
    },
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": 1000,
  "duration": 4200,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "result".

duration_api_msintegerRequired

duration_msintegerRequired

errorsarray<string> | nullOptional

Fields and variants

[]string

is_errorbooleanRequired

modelUsageobject | nullOptional

Additional properties are allowed.

num_turnsintegerRequired

resultstring | nullOptional

session_idstring | nullOptional

stop_reasonstring | nullOptional

structured_outputany JSON valueOptional

subtypestringRequired

total_cost_usdnumber | nullOptional

usageobject | nullOptional

Additional properties are allowed.

Fields and variants

cache_creationobject | nullOptional: Additional properties are allowed.
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
input_tokensintegerOptional
output_tokensintegerOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

conversation_resetReports that Claude switched to a new native conversation identifier.

Link to this event

Example JSON

{
  "kind": "claude_code",
  "source": "claude_code",
  "record_format": "claude_jsonl@1",
  "record_type": "conversation_reset",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "conversation_reset",
    "new_conversation_id": "33333333-3333-4333-8333-333333333333",
    "session_id": "11111111-1111-4111-8111-111111111111",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_code".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "conversation_reset".
new_conversation_idstringRequired
session_idstring | nullOptional
uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

system.subtype is an open string. Examples include init, compact_boundary, status, vcs_state_changed, task_started, task_progress, task_notification, task_updated, hook_started, and hook_response; these remain system records, not separate record_type values.

A result.subtype distinguishes success from outcomes such as error_during_execution, error_max_turns, error_max_structured_output_retries, and historical error_max_budget_usd results.

Content blocks such as text, thinking, tool_use, and tool_result are nested payloads, not separate session events. Native stream_event messages supply live delta frames; their original per-token messages are not retained as records.

Codex

Current Codex records use source: "codex" and record_format: "codex_app_server@1". The modeled notifications use kind: "codex_app_server"; additional native notifications use kind: "unknown" while retaining their method and payload.

remoteControl/status/changedReports the native app-server remote-control status as an unknown record.

Link to this event

Example JSON

{
  "kind": "unknown",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "remoteControl/status/changed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "remoteControl/status/changed",
    "params": {
      "status": "disabled",
      "serverName": "sandbox",
      "installationId": "installation_example",
      "environmentId": null
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "unknown".

sourcestringRequired

Original producer. Unknown producers remain readable as unknown records.

record_formatstringRequired

Original versioned payload format.

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

thread/startedAnnounces the native thread and its metadata.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "thread/started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "thread/started",
    "params": {
      "thread": {
        "id": "thread_example",
        "cliVersion": "0.145.0",
        "modelProvider": "openai",
        "cwd": "/workspace/api-repo",
        "turns": []
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

threadobjectRequired

Additional properties are allowed.

Fields and variants

cliVersionstringRequired

cwdstringRequired

idstringRequired

modelProviderstringRequired

turnsarray<object>Required

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

additionalDetailsstring | nullOptional

codexErrorInfostring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string
variant 2object: Additional properties are allowed.

messagestringRequired

idstringRequired

itemsarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "userMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "userMessage".

clientIdstring | nullOptional

contentarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "text".

textstringRequired

text_elementsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

type = "localImage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "localImage".
detailstring | nullOptional: Allowed values: "auto", "low", "high", "original".
pathstringRequired

idstringRequired

type = "agentMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agentMessage".
idstringRequired
phasestring | nullOptional: Allowed values: "commentary", "final_answer".
textstringRequired

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "reasoning".

contentarray<string>Optional

Fields and variants

[]string

idstringRequired

summaryarray<string>Optional

Fields and variants

[]string

type = "plan"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "plan".
idstringRequired
textstringRequired

type = "commandExecution"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "commandExecution".

aggregatedOutputstring | nullOptional

commandstringRequired

commandActionsarray<object>Required

Fields and variants

[]object: Additional properties are allowed.

cwdstringRequired

durationMsinteger | nullOptional

exitCodeinteger | nullOptional

idstringRequired

processIdstring | nullOptional

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "fileChange"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "fileChange".

changesarray<object>Required

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

kindobjectRequired: Additional properties are allowed.
diffstringRequired
pathstringRequired

idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "webSearch"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "webSearch".
actionobject | nullOptional: Additional properties are allowed.
idstringRequired
querystringRequired

type = "mcpToolCall"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "mcpToolCall".

appContextobject | nullOptional

Additional properties are allowed.

Fields and variants

actionNamestring | nullOptional
appNamestring | nullOptional
connectorIdstringRequired
linkIdstring | nullOptional
resourceUristring | nullOptional

argumentsany JSON valueRequired

durationMsinteger | nullOptional

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

messagestringRequired

idstringRequired

mcpAppResourceUristring | nullOptional

pluginIdstring | nullOptional

resultobject | nullOptional

Additional properties are allowed.

Fields and variants

_metaany JSON valueOptional

contentarray<any JSON value>Required

Fields and variants

[]any JSON value

structuredContentany JSON valueOptional

serverstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed".

toolstringRequired

type = "contextCompaction"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "contextCompaction".
idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "interrupted".

methodstringRequired

Must be "thread/started".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

thread/status/changedReports native thread activity, such as becoming active or idle, as an unknown record.

Link to this event

Example JSON

{
  "kind": "unknown",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "thread/status/changed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "thread/status/changed",
    "params": {
      "threadId": "thread_example",
      "status": {
        "type": "idle"
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "unknown".

sourcestringRequired

Original producer. Unknown producers remain readable as unknown records.

record_formatstringRequired

Original versioned payload format.

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn/startedAnnounces the start of a native turn.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "turn/started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "turn/started",
    "params": {
      "threadId": "thread_example",
      "turn": {
        "id": "native_turn_example",
        "status": "inProgress",
        "items": [],
        "error": null
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

threadIdstringRequired

turnobjectRequired

Additional properties are allowed.

Fields and variants

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

additionalDetailsstring | nullOptional

codexErrorInfostring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string
variant 2object: Additional properties are allowed.

messagestringRequired

idstringRequired

itemsarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "userMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "userMessage".

clientIdstring | nullOptional

contentarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "text".

textstringRequired

text_elementsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

type = "localImage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "localImage".
detailstring | nullOptional: Allowed values: "auto", "low", "high", "original".
pathstringRequired

idstringRequired

type = "agentMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agentMessage".
idstringRequired
phasestring | nullOptional: Allowed values: "commentary", "final_answer".
textstringRequired

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "reasoning".

contentarray<string>Optional

Fields and variants

[]string

idstringRequired

summaryarray<string>Optional

Fields and variants

[]string

type = "plan"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "plan".
idstringRequired
textstringRequired

type = "commandExecution"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "commandExecution".

aggregatedOutputstring | nullOptional

commandstringRequired

commandActionsarray<object>Required

Fields and variants

[]object: Additional properties are allowed.

cwdstringRequired

durationMsinteger | nullOptional

exitCodeinteger | nullOptional

idstringRequired

processIdstring | nullOptional

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "fileChange"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "fileChange".

changesarray<object>Required

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

kindobjectRequired: Additional properties are allowed.
diffstringRequired
pathstringRequired

idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "webSearch"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "webSearch".
actionobject | nullOptional: Additional properties are allowed.
idstringRequired
querystringRequired

type = "mcpToolCall"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "mcpToolCall".

appContextobject | nullOptional

Additional properties are allowed.

Fields and variants

actionNamestring | nullOptional
appNamestring | nullOptional
connectorIdstringRequired
linkIdstring | nullOptional
resourceUristring | nullOptional

argumentsany JSON valueRequired

durationMsinteger | nullOptional

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

messagestringRequired

idstringRequired

mcpAppResourceUristring | nullOptional

pluginIdstring | nullOptional

resultobject | nullOptional

Additional properties are allowed.

Fields and variants

_metaany JSON valueOptional

contentarray<any JSON value>Required

Fields and variants

[]any JSON value

structuredContentany JSON valueOptional

serverstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed".

toolstringRequired

type = "contextCompaction"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "contextCompaction".
idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "interrupted".

methodstringRequired

Must be "turn/started".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

item/startedAnnounces the start of a message, command, file change, or another conversation item.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "item/started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "item/started",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "item": {
        "type": "commandExecution",
        "id": "command_example",
        "command": "pytest -q",
        "cwd": "/workspace/api-repo",
        "commandActions": [],
        "status": "inProgress"
      }
    }
  },
  "tools": [
    "Bash"
  ],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

itemobjectRequired

Matches exactly one variant below.

Fields and variants

type = "userMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "userMessage".

clientIdstring | nullOptional

contentarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "text".

textstringRequired

text_elementsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

type = "localImage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "localImage".
detailstring | nullOptional: Allowed values: "auto", "low", "high", "original".
pathstringRequired

idstringRequired

type = "agentMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agentMessage".
idstringRequired
phasestring | nullOptional: Allowed values: "commentary", "final_answer".
textstringRequired

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "reasoning".

contentarray<string>Optional

Fields and variants

[]string

idstringRequired

summaryarray<string>Optional

Fields and variants

[]string

type = "plan"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "plan".
idstringRequired
textstringRequired

type = "commandExecution"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "commandExecution".

aggregatedOutputstring | nullOptional

commandstringRequired

commandActionsarray<object>Required

Fields and variants

[]object: Additional properties are allowed.

cwdstringRequired

durationMsinteger | nullOptional

exitCodeinteger | nullOptional

idstringRequired

processIdstring | nullOptional

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "fileChange"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "fileChange".

changesarray<object>Required

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

kindobjectRequired: Additional properties are allowed.
diffstringRequired
pathstringRequired

idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "webSearch"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "webSearch".
actionobject | nullOptional: Additional properties are allowed.
idstringRequired
querystringRequired

type = "mcpToolCall"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "mcpToolCall".

appContextobject | nullOptional

Additional properties are allowed.

Fields and variants

actionNamestring | nullOptional
appNamestring | nullOptional
connectorIdstringRequired
linkIdstring | nullOptional
resourceUristring | nullOptional

argumentsany JSON valueRequired

durationMsinteger | nullOptional

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

messagestringRequired

idstringRequired

mcpAppResourceUristring | nullOptional

pluginIdstring | nullOptional

resultobject | nullOptional

Additional properties are allowed.

Fields and variants

_metaany JSON valueOptional

contentarray<any JSON value>Required

Fields and variants

[]any JSON value

structuredContentany JSON valueOptional

serverstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed".

toolstringRequired

type = "contextCompaction"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "contextCompaction".
idstringRequired

threadIdstringRequired

turnIdstringRequired

methodstringRequired

Must be "item/started".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

item/completedSupplies a completed item, including its content, output, or outcome.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "item/completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "item/completed",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "item": {
        "type": "commandExecution",
        "id": "command_example",
        "command": "pytest -q",
        "cwd": "/workspace/api-repo",
        "commandActions": [],
        "status": "completed",
        "aggregatedOutput": "12 passed",
        "exitCode": 0,
        "durationMs": 4200
      }
    }
  },
  "tools": [
    "Bash"
  ],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

itemobjectRequired

Matches exactly one variant below.

Fields and variants

type = "userMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "userMessage".

clientIdstring | nullOptional

contentarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "text".

textstringRequired

text_elementsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

type = "localImage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "localImage".
detailstring | nullOptional: Allowed values: "auto", "low", "high", "original".
pathstringRequired

idstringRequired

type = "agentMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agentMessage".
idstringRequired
phasestring | nullOptional: Allowed values: "commentary", "final_answer".
textstringRequired

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "reasoning".

contentarray<string>Optional

Fields and variants

[]string

idstringRequired

summaryarray<string>Optional

Fields and variants

[]string

type = "plan"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "plan".
idstringRequired
textstringRequired

type = "commandExecution"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "commandExecution".

aggregatedOutputstring | nullOptional

commandstringRequired

commandActionsarray<object>Required

Fields and variants

[]object: Additional properties are allowed.

cwdstringRequired

durationMsinteger | nullOptional

exitCodeinteger | nullOptional

idstringRequired

processIdstring | nullOptional

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "fileChange"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "fileChange".

changesarray<object>Required

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

kindobjectRequired: Additional properties are allowed.
diffstringRequired
pathstringRequired

idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "webSearch"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "webSearch".
actionobject | nullOptional: Additional properties are allowed.
idstringRequired
querystringRequired

type = "mcpToolCall"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "mcpToolCall".

appContextobject | nullOptional

Additional properties are allowed.

Fields and variants

actionNamestring | nullOptional
appNamestring | nullOptional
connectorIdstringRequired
linkIdstring | nullOptional
resourceUristring | nullOptional

argumentsany JSON valueRequired

durationMsinteger | nullOptional

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

messagestringRequired

idstringRequired

mcpAppResourceUristring | nullOptional

pluginIdstring | nullOptional

resultobject | nullOptional

Additional properties are allowed.

Fields and variants

_metaany JSON valueOptional

contentarray<any JSON value>Required

Fields and variants

[]any JSON value

structuredContentany JSON valueOptional

serverstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed".

toolstringRequired

type = "contextCompaction"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "contextCompaction".
idstringRequired

threadIdstringRequired

turnIdstringRequired

methodstringRequired

Must be "item/completed".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

thread/tokenUsage/updatedReports cumulative native thread usage and usage for the latest model call.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "thread/tokenUsage/updated",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "thread/tokenUsage/updated",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "tokenUsage": {
        "total": {
          "inputTokens": 1200,
          "outputTokens": 80,
          "cachedInputTokens": 0,
          "reasoningOutputTokens": 0,
          "totalTokens": 1280
        },
        "last": {
          "inputTokens": 1200,
          "outputTokens": 80,
          "cachedInputTokens": 0,
          "reasoningOutputTokens": 0,
          "totalTokens": 1280
        },
        "modelContextWindow": 272000
      }
    }
  },
  "tools": null,
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

threadIdstringRequired

tokenUsageobjectRequired

Additional properties are allowed.

Fields and variants

lastobjectRequired

Additional properties are allowed.

Fields and variants

cacheWriteInputTokensintegerOptional
cachedInputTokensintegerRequired
inputTokensintegerRequired
outputTokensintegerRequired
reasoningOutputTokensintegerRequired
totalTokensintegerRequired

modelContextWindowinteger | nullOptional

totalobjectRequired

Additional properties are allowed.

Fields and variants

cacheWriteInputTokensintegerOptional
cachedInputTokensintegerRequired
inputTokensintegerRequired
outputTokensintegerRequired
reasoningOutputTokensintegerRequired
totalTokensintegerRequired

turnIdstringRequired

methodstringRequired

Must be "thread/tokenUsage/updated".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

account/rateLimits/updatedReports native account rate-limit information as an unknown record.

Link to this event

Example JSON

{
  "kind": "unknown",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "account/rateLimits/updated",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": null,
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "account/rateLimits/updated",
    "params": {
      "rateLimits": {
        "limitId": "codex",
        "limitName": null,
        "primary": null,
        "secondary": null,
        "credits": null,
        "planType": null
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "unknown".

sourcestringRequired

Original producer. Unknown producers remain readable as unknown records.

record_formatstringRequired

Original versioned payload format.

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

errorReports a native error and whether Codex intends to retry it.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "error",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "error",
    "params": {
      "threadId": "thread_example",
      "turnId": "native_turn_example",
      "error": {
        "message": "The model request timed out."
      },
      "willRetry": true
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

errorobjectRequired

Additional properties are allowed.

Fields and variants

additionalDetailsstring | nullOptional

codexErrorInfostring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string
variant 2object: Additional properties are allowed.

messagestringRequired

threadIdstringRequired

turnIdstringRequired

willRetrybooleanRequired

methodstringRequired

Must be "error".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn/completedReports a native turn ending with status completed, failed, or interrupted.

Link to this event

Example JSON

{
  "kind": "codex_app_server",
  "source": "codex",
  "record_format": "codex_app_server@1",
  "record_type": "turn/completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "method": "turn/completed",
    "params": {
      "threadId": "thread_example",
      "turn": {
        "id": "native_turn_example",
        "status": "completed",
        "items": [],
        "error": null
      }
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex_app_server".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_app_server@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

paramsobjectRequired

Additional properties are allowed.

Fields and variants

threadIdstringRequired

turnobjectRequired

Additional properties are allowed.

Fields and variants

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

additionalDetailsstring | nullOptional

codexErrorInfostring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string
variant 2object: Additional properties are allowed.

messagestringRequired

idstringRequired

itemsarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "userMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "userMessage".

clientIdstring | nullOptional

contentarray<object>Required

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "text".

textstringRequired

text_elementsarray<object>Optional

Fields and variants

[]object: Additional properties are allowed.

type = "localImage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "localImage".
detailstring | nullOptional: Allowed values: "auto", "low", "high", "original".
pathstringRequired

idstringRequired

type = "agentMessage"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agentMessage".
idstringRequired
phasestring | nullOptional: Allowed values: "commentary", "final_answer".
textstringRequired

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "reasoning".

contentarray<string>Optional

Fields and variants

[]string

idstringRequired

summaryarray<string>Optional

Fields and variants

[]string

type = "plan"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "plan".
idstringRequired
textstringRequired

type = "commandExecution"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "commandExecution".

aggregatedOutputstring | nullOptional

commandstringRequired

commandActionsarray<object>Required

Fields and variants

[]object: Additional properties are allowed.

cwdstringRequired

durationMsinteger | nullOptional

exitCodeinteger | nullOptional

idstringRequired

processIdstring | nullOptional

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "fileChange"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "fileChange".

changesarray<object>Required

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

kindobjectRequired: Additional properties are allowed.
diffstringRequired
pathstringRequired

idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "declined".

type = "webSearch"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "webSearch".
actionobject | nullOptional: Additional properties are allowed.
idstringRequired
querystringRequired

type = "mcpToolCall"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "mcpToolCall".

appContextobject | nullOptional

Additional properties are allowed.

Fields and variants

actionNamestring | nullOptional
appNamestring | nullOptional
connectorIdstringRequired
linkIdstring | nullOptional
resourceUristring | nullOptional

argumentsany JSON valueRequired

durationMsinteger | nullOptional

errorobject | nullOptional

Additional properties are allowed.

Fields and variants

messagestringRequired

idstringRequired

mcpAppResourceUristring | nullOptional

pluginIdstring | nullOptional

resultobject | nullOptional

Additional properties are allowed.

Fields and variants

_metaany JSON valueOptional

contentarray<any JSON value>Required

Fields and variants

[]any JSON value

structuredContentany JSON valueOptional

serverstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed".

toolstringRequired

type = "contextCompaction"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "contextCompaction".
idstringRequired

statusstringRequired

Allowed values: "inProgress", "completed", "failed", "interrupted".

methodstringRequired

Must be "turn/completed".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

An item's type distinguishes userMessage, agentMessage, reasoning, plan, commandExecution, fileChange, webSearch, mcpToolCall, and contextCompaction. These are item variants inside notifications, not separate event methods.

item/agentMessage/delta supplies live delta frames. Native incremental tool, plan, and reasoning notifications are not forwarded as separate customer events; completed items carry their durable content. Native RPC acknowledgements are not session records.

WebSocket frames

Connect using the Python SDK or TypeScript SDK. The public endpoint is wss://api.ellipsis.dev/v1/sessions/{session_id}/stream?protocol=4; authenticate with a bearer token.

Each WebSocket message contains one frame. records_append is the only frame that advances the resume cursor. Reconnect with after_seq set to the last received feed_seq, or let the SDK manage reconnects. If after_seq is less than earliest_feed_seq - 1, part of the requested history is no longer retained.

snapshotThe first frame contains the current session, pending inbox messages, and the earliest retained feed position; records follow separately.

Link to this event

Example JSON

{
  "type": "snapshot",
  "protocol": 4,
  "earliest_feed_seq": 1,
  "session": {
    "id": "session_example",
    "harness": "claude_code",
    "source": "api",
    "status": "running",
    "status_reason": null,
    "session_state": "running",
    "exit_status": null,
    "attribution": {
      "type": "api_key",
      "id": "key_example",
      "user": null
    },
    "automation": null,
    "budget": {
      "cents": 300,
      "source": "run"
    },
    "config": {
      "harness": {
        "type": "claude_code",
        "model": "claude-sonnet-5"
      },
      "instructions": "Run relevant tests.",
      "environment": {
        "repositories": []
      },
      "budget": {
        "session": 3
      }
    },
    "context_repository": null,
    "cost": {
      "llm": 0,
      "sandbox_cpu": 0,
      "sandbox_memory": 0,
      "fee": 0,
      "total": 0
    },
    "environment": {
      "environment_id": null,
      "source": "platform_default"
    },
    "git": null,
    "created_at": "2026-09-10T14:00:00Z",
    "updated_at": "2026-09-10T14:00:00Z",
    "last_activity_at": "2026-09-10T14:00:00Z",
    "last_message_at": "2026-09-10T14:00:00Z",
    "metadata": {},
    "parent": {
      "kind": null,
      "session_id": null,
      "replayed_from_session_id": null
    },
    "prompt": "Run the tests and report failures.",
    "prompting": {
      "enabled": true,
      "blocked_reason": null,
      "detail": null,
      "surface_name": null
    },
    "stopped": {
      "at": null,
      "by": null,
      "by_user": null
    },
    "summary": null,
    "surface": {
      "session": "alive",
      "run": "working",
      "status": "working"
    },
    "tokens": {
      "input": 0,
      "output": 0,
      "cache_read": 0,
      "cache_creation": 0,
      "total": 0,
      "model": "claude-sonnet-5"
    },
    "trigger": null
  },
  "messages": []
}

Field specification

typestringRequired

Must be "snapshot".

earliest_feed_seqinteger | nullRequired

The retention head: the lowest feed_seq still stored for this session, or null when it has no stored records. A client resuming from after_seq < earliest_feed_seq - 1 knows history is truncated.

messagesarray<object>Required

The session's open (pending) inbox messages.

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

authorstring | nullRequired

Display attribution of the message's sender.

bodystringRequired

The message text, with one `[Image #N]` placeholder per attached image.

created_atstringRequired

When the message was created. Format: date-time.

delivered_atstring | nullRequired

When the message was delivered to the agent, if it has been. Format: date-time.

delivered_turn_idstring | nullRequired

Identifier of the turn the message was delivered into, if any.

feed_seqinteger | nullRequired

Where the message sits in the session's feed — placement metadata only, NOT a resume cursor (only records_append frames advance the cursor). Null for older rows.

idstringRequired

Unique identifier of the message.

imagesarray<object>Required

Images attached to the message, metadata only: index, media type, size. The bytes go to the model, never over the stream.

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

indexintegerRequired: 1-based position: the N in `[Image #N]`.
media_typestringRequired: The image's MIME type.
size_bytesintegerRequired: Size of the decoded image, in bytes.

sender_attribution_idstring | nullRequired

Identifier of the principal that sent the message, if attributed.

sender_attribution_typestring | nullRequired

Kind of principal that sent the message, if attributed. Allowed values: "github_user", "linear_user", "slack_user", "api_key".

session_idstringRequired

Identifier of the session the message belongs to.

statusstringRequired

Delivery status of the message. Allowed values: "pending", "delivered".

protocolintegerRequired

Echoes the protocol version the server is serving.

sessionobjectRequired

The session's current state. Additional properties are allowed.

Fields and variants

sourcestringRequired

Where the session came from (e.g. react, web, api, cli, mention, cron). Allowed values: "react", "web", "api", "cli", "mention", "cron".

attributionobjectRequired

The principal this session is attributed to. Additional properties are allowed.

Fields and variants

typestring | nullOptional

Kind of principal the session is attributed to (e.g. a GitHub user or an API key). Allowed values: "github_user", "linear_user", "slack_user", "api_key".

idstring | nullOptional

Identifier of the principal the session is attributed to.

userobject | nullOptional

The GitHub user the session is attributed to, resolved at read time. Null when the attribution is not a GitHub user. Additional properties are allowed.

Fields and variants

typestringRequired: Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired

automationobject | nullRequired

The automation the session was started from, or null for a raw session started with POST /v1/sessions. Additional properties are allowed.

Fields and variants

configobjectRequired

The automation definition the session was started from, frozen when the session was created. Additional properties are not allowed.

Fields and variants

ellipsisobjectOptional

Additional properties are not allowed.

Fields and variants

descriptionstring | nullOptional

enabledbooleanOptional

metadataobjectOptional

Additional properties are not allowed.

Fields and variants

annotationsobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

labelsarray<string>Optional

Fields and variants

[]string

namestring | nullOptional

versionstringOptional

inputobject | nullOptional

Additional properties are not allowed.

Fields and variants

json_schemaobject | nullOptional: Additional properties are allowed.
messagestring | nullOptional

sessionobjectRequired

Additional properties are not allowed.

Fields and variants

budgetobjectOptional

Additional properties are not allowed.

Fields and variants

daynumber | nullOptional
monthnumber | nullOptional
sessionnumber | nullOptional
weeknumber | nullOptional

environmentstring | objectOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

computeobjectOptional

Additional properties are not allowed.

Fields and variants

cpuinteger | nullOptional

Minimum: 2. Maximum: 32.

memorystring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

gbinteger | nullOptional: Minimum: 0.
mbinteger | nullOptional: Minimum: 0.

timeoutstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

hoursinteger | nullOptional: Minimum: 0.
minutesinteger | nullOptional: Minimum: 0.
secondsinteger | nullOptional: Minimum: 0.

hooksobjectOptional

Additional properties are not allowed.

Fields and variants

post_clonestring | nullOptional
post_startstring | nullOptional

imageobjectOptional

Additional properties are not allowed.

Fields and variants

dockerfile_appendstring | nullOptional
setupstring | nullOptional

mcp_serversarray<string | object>Optional

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

namestringRequired

variant 3object

Additional properties are not allowed.

Fields and variants

argsarray<string>Optional

Fields and variants

[]string

commandstringRequired

envobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

variant 4object

Additional properties are not allowed.

Fields and variants

headersobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

urlstringRequired

repositoriesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variablesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
valuestring | nullOptional

harnessobjectRequired

The explicitly selected harness and its native options. Matches exactly one variant below.

Fields and variants

type = "claude_code"object

Additional properties are not allowed.

Fields and variants

typestringRequired

Must be "claude_code".

effortstring | nullOptional

Allowed values: "low", "medium", "high", "xhigh", "max".

fallback_modelstring | nullOptional

max_turnsinteger | nullOptional

Greater than: 0.

modelstring | nullOptional

settingsobject | nullOptional

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

type = "codex"object

Additional properties are not allowed.

Fields and variants

typestringRequired: Must be "codex".
effortstring | nullOptional: Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringOptional

instructionsstring | object | array<string | object>Optional

Instructions appended to the harness's own prompt. Text and repository file references are resolved in order. Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

outputobject | nullOptional

Additional properties are not allowed.

Fields and variants

json_schemaobjectRequired: Additional properties are allowed.

permissionsobjectOptional

Additional properties are not allowed.

Fields and variants

ellipsisany JSON value | objectOptional

Matches at least one variant below.

Fields and variants

variant 1any JSON value

Allowed values: true, "all".

variant 2object

Additional properties are allowed. Allowed keys: "account", "alerts", "sessions", "files", "memories", "reviews", "configs", "defaults", "environments", "secrets", "templates", "integrations", "tokens", "webhooks", "user".

Fields and variants

[key]string | object | array<string | object>

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

githubobjectOptional

Additional properties are not allowed.

Fields and variants

permissionsstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

Must be "read_only".

variant 2object

Additional properties are allowed.

Fields and variants

[key]string

repositoriesarray<string> | nullOptional

Fields and variants

[]string

skillsarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

triggerobject | nullOptional

Matches exactly one variant below.

Fields and variants

type = "cron"object

Additional properties are not allowed.

Fields and variants

typestringOptional: Must be "cron".
schedulestringRequired

type = "react"object

Additional properties are not allowed.

Fields and variants

typestringOptional

Must be "react".

issueobject | nullOptional

Additional properties are not allowed.

Fields and variants

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

One include-minus-exclude set of GitHub accounts: an account matches iff it is in `include` (`true` = all, a list = exactly those, `false`/`[]` = none) AND not in `exclude`. A bare bool or list is shorthand for `include`, so `users: true` and `users: [priya-shah]` both parse. Additional properties are not allowed.

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

labelsarray<string>Optional

Fields and variants

[]string

onarray<string>Required

Fields and variants

[]string: Allowed values: "opened", "closed", "commented".

repositoriesobject | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

The watch scope of a trigger, by repository name (owner defaults to the account). Include minus exclude: `include: []` (the default) covers every repository of the installation, so `exclude`-only means "all except these" and keeps covering repositories added to the org later. A bare list is shorthand for `include`. Additional properties are not allowed.

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string>Optional

Fields and variants

[]string

variant 2array<string>

Fields and variants

[]string

linear_issueobject | nullOptional

Additional properties are not allowed.

Fields and variants

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

onarray<string>Optional

Fields and variants

[]string: Allowed values: "opened".

pull_requestobject | nullOptional

Additional properties are not allowed.

Fields and variants

basearray<string>Optional

Fields and variants

[]string

draftboolean | nullOptional

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

headarray<string>Optional

Fields and variants

[]string

labelsarray<string>Optional

Fields and variants

[]string

onarray<string>Required

Fields and variants

[]string: Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented".

pathsarray<string>Optional

Fields and variants

[]string

repositoriesobject | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string>Optional

Fields and variants

[]string

variant 2array<string>

Fields and variants

[]string

pushobject | nullOptional

Additional properties are not allowed.

Fields and variants

brancharray<string>Optional

Fields and variants

[]string

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

pathsarray<string>Optional

Fields and variants

[]string

repositoriesobject | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string>Optional

Fields and variants

[]string

variant 2array<string>

Fields and variants

[]string

sentryobject | nullOptional

Additional properties are not allowed.

Fields and variants

onarray<string>Required

Fields and variants

[]string: Allowed values: "issue_alert", "metric_alert".

projectsarray<string>Optional

Fields and variants

[]string

slack_channelobject | nullOptional

Additional properties are not allowed.

idstring | nullOptional

Identifier of the saved automation this session's snapshot was taken from. Null for a routing-file agent, a code-review stage agent, or the built-in mention agent, which have no saved automation behind them. Points at the automation as it exists now, which may have changed since.

budgetobjectRequired

The spend budget enforced for this session. Additional properties are allowed.

Fields and variants

sourcestringOptional: Where the resolved budget came from. Allowed values: "system", "account", "config", "run".
centsintegerOptional: The spend budget resolved for this session, in cents.

configobjectRequired

What the session ran on, frozen when it was created: the harness block, the resolved environment, permissions, skills, output contract, and budget. Additional properties are not allowed.

Fields and variants

budgetobjectOptional

Additional properties are not allowed.

Fields and variants

daynumber | nullOptional
monthnumber | nullOptional
sessionnumber | nullOptional
weeknumber | nullOptional

environmentstring | objectOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

computeobjectOptional

Additional properties are not allowed.

Fields and variants

cpuinteger | nullOptional

Minimum: 2. Maximum: 32.

memorystring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

gbinteger | nullOptional: Minimum: 0.
mbinteger | nullOptional: Minimum: 0.

timeoutstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

hoursinteger | nullOptional: Minimum: 0.
minutesinteger | nullOptional: Minimum: 0.
secondsinteger | nullOptional: Minimum: 0.

hooksobjectOptional

Additional properties are not allowed.

Fields and variants

post_clonestring | nullOptional
post_startstring | nullOptional

imageobjectOptional

Additional properties are not allowed.

Fields and variants

dockerfile_appendstring | nullOptional
setupstring | nullOptional

mcp_serversarray<string | object>Optional

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

namestringRequired

variant 3object

Additional properties are not allowed.

Fields and variants

argsarray<string>Optional

Fields and variants

[]string

commandstringRequired

envobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

variant 4object

Additional properties are not allowed.

Fields and variants

headersobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

urlstringRequired

repositoriesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variablesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
valuestring | nullOptional

harnessobjectRequired

The explicitly selected harness and its native options. Matches exactly one variant below.

Fields and variants

type = "claude_code"object

Additional properties are not allowed.

Fields and variants

typestringRequired

Must be "claude_code".

effortstring | nullOptional

Allowed values: "low", "medium", "high", "xhigh", "max".

fallback_modelstring | nullOptional

max_turnsinteger | nullOptional

Greater than: 0.

modelstring | nullOptional

settingsobject | nullOptional

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

type = "codex"object

Additional properties are not allowed.

Fields and variants

typestringRequired: Must be "codex".
effortstring | nullOptional: Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringOptional

instructionsstring | object | array<string | object>Optional

Instructions appended to the harness's own prompt. Text and repository file references are resolved in order. Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

outputobject | nullOptional

Additional properties are not allowed.

Fields and variants

json_schemaobjectRequired: Additional properties are allowed.

permissionsobjectOptional

Additional properties are not allowed.

Fields and variants

ellipsisany JSON value | objectOptional

Matches at least one variant below.

Fields and variants

variant 1any JSON value

Allowed values: true, "all".

variant 2object

Fields and variants

[key]string | object | array<string | object>

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

githubobjectOptional

Additional properties are not allowed.

Fields and variants

permissionsstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

Must be "read_only".

variant 2object

Additional properties are allowed.

Fields and variants

[key]string

repositoriesarray<string> | nullOptional

Fields and variants

[]string

skillsarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

context_repositorystring | nullRequired

The "owner/name" repository context the session was started in, if any.

costobjectRequired

What the session cost, in millicents, broken down by leg and carrying its own total. Additional properties are allowed.

Fields and variants

feeintegerOptional: Platform fee in millicents.
llmintegerOptional: LLM spend in millicents.
sandbox_cpuintegerOptional: Sandbox CPU spend in millicents.
sandbox_memoryintegerOptional: Sandbox memory spend in millicents.
totalintegerOptional: The grand total in millicents: llm + sandbox_cpu + sandbox_memory + fee.

created_atstringRequired

When the session was created. Format: date-time.

environmentobjectRequired

The environment the session resolved: the saved environment's id and how it was chosen. The environment's frozen body is `config.environment`. Additional properties are allowed.

Fields and variants

sourcestring | nullOptional: How the environment was chosen (request, automation, platform_default; repo_default and account_default on sessions from before those ladders were removed). Null when the config carried its own inline environment. Allowed values: "request", "automation", "repo_default", "account_default", "platform_default".
environment_idstring | nullOptional: Identifier of the saved environment the session's config resolved. Null for an inline environment block or the built-in basic sandbox.

exit_statusstring | nullRequired

How the session ended; null until it is terminal. Allowed values: "completed", "budget_hit", "payment_required", "tool_call_failed", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_sandbox_variables", "blocked", "contact_email_required", "cancelled", "interrupted", "error", "stopped".

gitobject | nullRequired

What the session did to git, one entry per repository in its workspace: the commit and branch it sits on, per-file line counts for its uncommitted changes, and the pull requests it opened. Null if nothing was ever captured. Additional properties are allowed.

Fields and variants

reposarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

commitsarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

committed_atstringRequired: Format: date-time.
pushedbooleanRequired
shastringRequired
subjectstringRequired

commits_totalintegerOptional

full_namestringRequired

local_commitstring | nullOptional

local_uncommitted_filesarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

additionsintegerRequired
deletionsintegerRequired
pathstringRequired
statusstringRequired

prsarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

gh_pr_idinteger | nullOptional
numberintegerRequired
titlestring | nullOptional
urlstringRequired

remote_branchstring | nullOptional

remote_commitstring | nullOptional

harnessstringRequired

The coding-agent harness the session runs on. Allowed values: "claude_code", "codex".

idstringRequired

Unique identifier of the session.

last_activity_atstring | nullRequired

When the session last showed activity. Format: date-time.

last_message_atstring | nullRequired

When the session last received a message. Format: date-time.

metadataobjectRequired

Caller-supplied metadata key-value pairs. Additional properties are allowed.

Fields and variants

[key]string

parentobjectRequired

What preceded this session, if anything. Additional properties are allowed.

Fields and variants

kindstring | nullOptional: How this session relates to its parent session, if any. Allowed values: "continuation", "resume".
replayed_from_session_idstring | nullOptional: Identifier of the original session this one was replayed from, if it was started via replay.
session_idstring | nullOptional: Identifier of the parent session that spawned this one, if any.

promptstring | nullRequired

The per-session prompt the session was started with.

promptingobjectRequired

Whether a client may send this session a message and, when it may not, the reason to show instead of a composer. Additional properties are allowed.

Fields and variants

blocked_reasonstring | nullOptional: Allowed values: "mention_surface", "ephemeral_trigger", "non_interactive", "harness_single_turn", "closed".
detailstring | nullOptional
enabledbooleanRequired
surface_namestring | nullOptional

session_statestring | nullRequired

Lifecycle state of the durable conversation, or null for sessions without one. Allowed values: "idle", "running", "closed".

statusstringRequired

Execution status of the session. Allowed values: "scheduled", "creating_sandbox", "running", "retrying", "completed", "error", "cancelled", "stopped".

status_reasonstring | nullRequired

Human-readable reason for the current status, when there is one.

stoppedobjectRequired

The stop request, if the session was stopped. Additional properties are allowed.

Fields and variants

atstring | nullOptional

When a stop was requested, if one was. Format: date-time.

byinteger | nullOptional

GitHub account id of the user who stopped the session, if known.

by_userobject | nullOptional

The GitHub user who stopped the session, resolved at read time. Additional properties are allowed.

Fields and variants

typestringRequired: Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired

summaryobject | nullRequired

The latest live summary of the session's progress while it runs, and when it was generated. Additional properties are allowed.

Fields and variants

created_atstring | nullOptional: When this summary line was generated. Null on summaries written before generation time was tracked. Format: date-time.
descriptionstringRequired: One-line description of what the session is working on.

surfaceobjectRequired

The public status projection: the durable conversation (`session`), the current execution (`run`), and the one derived `status` word. Additional properties are allowed.

Fields and variants

runstring | nullRequired: Allowed values: "scheduled", "starting", "working", "waiting", "done", "failed", "stopped", "cancelled", "retrying".
sessionstring | nullRequired: Allowed values: "alive", "idle", "closed".
statusstring | nullRequired

tokensobjectRequired

The tokens the session spent and the model they went to. `total` includes the prompt-cache lanes. Additional properties are allowed.

Fields and variants

cache_creationintegerOptional: Tokens written to the prompt cache.
cache_readintegerOptional: Tokens read from the prompt cache.
inputintegerOptional: Input tokens used.
modelstringOptional: The model the token counts are attributed to.
outputintegerOptional: Output tokens used.
totalintegerOptional: Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on.

triggerobject | nullRequired

The external event that started the session. Additional properties are allowed.

Fields and variants

actionstring | nullOptional

actorobject | nullOptional

Additional properties are allowed.

Fields and variants

avatar_urlstring | nullOptional
is_botbooleanOptional
namestringRequired

branchstring | nullOptional

numberinteger | nullOptional

repositorystring | nullOptional

surfacestring | nullOptional

titlestring | nullOptional

urlstring | nullOptional

updated_atstringRequired

When the session was last updated. Format: date-time.

records_appendDelivers a batch of retained or newly produced records in feed_seq order.

Link to this event

Example JSON

{
  "type": "records_append",
  "records": [
    {
      "kind": "platform",
      "source": "lifecycle",
      "record_format": "ellipsis_lifecycle@1",
      "record_type": "turn_started",
      "id": "record_example",
      "session_id": "session_example",
      "session_execution_id": "execution_example",
      "agent_turn_id": "turn_example",
      "session_message_id": null,
      "sandbox_id": "sandbox_example",
      "feed_seq": 12,
      "stream_seq": 8,
      "payload": {
        "turn_id": "turn_example",
        "turn_index": 0
      },
      "tools": null,
      "tokens_info": null,
      "cost": null,
      "duration": null,
      "model": null,
      "created_at": "2026-09-10T14:00:00Z"
    }
  ]
}

Field specification

typestringRequired

Must be "records_append".

recordsarray<SessionRecord>Required

New session records, ordered by feed_seq.

Fields and variants

[]SessionRecord: See the record variants in Platform, Claude Code, Codex, and Historical formats.

sessionReplaces the current session object when its public fields change, including status, progress, and cost.

Link to this event

Example JSON

{
  "type": "session",
  "session": {
    "id": "session_example",
    "harness": "claude_code",
    "source": "api",
    "status": "running",
    "status_reason": null,
    "session_state": "running",
    "exit_status": null,
    "attribution": {
      "type": "api_key",
      "id": "key_example",
      "user": null
    },
    "automation": null,
    "budget": {
      "cents": 300,
      "source": "run"
    },
    "config": {
      "harness": {
        "type": "claude_code",
        "model": "claude-sonnet-5"
      },
      "instructions": "Run relevant tests.",
      "environment": {
        "repositories": []
      },
      "budget": {
        "session": 3
      }
    },
    "context_repository": null,
    "cost": {
      "llm": 0,
      "sandbox_cpu": 0,
      "sandbox_memory": 0,
      "fee": 0,
      "total": 0
    },
    "environment": {
      "environment_id": null,
      "source": "platform_default"
    },
    "git": null,
    "created_at": "2026-09-10T14:00:00Z",
    "updated_at": "2026-09-10T14:00:05Z",
    "last_activity_at": "2026-09-10T14:00:00Z",
    "last_message_at": "2026-09-10T14:00:00Z",
    "metadata": {},
    "parent": {
      "kind": null,
      "session_id": null,
      "replayed_from_session_id": null
    },
    "prompt": "Run the tests and report failures.",
    "prompting": {
      "enabled": true,
      "blocked_reason": null,
      "detail": null,
      "surface_name": null
    },
    "stopped": {
      "at": null,
      "by": null,
      "by_user": null
    },
    "summary": {
      "description": "Running the test suite.",
      "created_at": "2026-09-10T14:00:05Z"
    },
    "surface": {
      "session": "alive",
      "run": "working",
      "status": "working"
    },
    "tokens": {
      "input": 0,
      "output": 0,
      "cache_read": 0,
      "cache_creation": 0,
      "total": 0,
      "model": "claude-sonnet-5"
    },
    "trigger": null
  }
}

Field specification

typestringRequired

Must be "session".

sessionobjectRequired

The session's current state. Additional properties are allowed.

Fields and variants

sourcestringRequired

Where the session came from (e.g. react, web, api, cli, mention, cron). Allowed values: "react", "web", "api", "cli", "mention", "cron".

attributionobjectRequired

The principal this session is attributed to. Additional properties are allowed.

Fields and variants

typestring | nullOptional

Kind of principal the session is attributed to (e.g. a GitHub user or an API key). Allowed values: "github_user", "linear_user", "slack_user", "api_key".

idstring | nullOptional

Identifier of the principal the session is attributed to.

userobject | nullOptional

The GitHub user the session is attributed to, resolved at read time. Null when the attribution is not a GitHub user. Additional properties are allowed.

Fields and variants

typestringRequired: Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired

automationobject | nullRequired

The automation the session was started from, or null for a raw session started with POST /v1/sessions. Additional properties are allowed.

Fields and variants

configobjectRequired

The automation definition the session was started from, frozen when the session was created. Additional properties are not allowed.

Fields and variants

ellipsisobjectOptional

Additional properties are not allowed.

Fields and variants

descriptionstring | nullOptional

enabledbooleanOptional

metadataobjectOptional

Additional properties are not allowed.

Fields and variants

annotationsobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

labelsarray<string>Optional

Fields and variants

[]string

namestring | nullOptional

versionstringOptional

inputobject | nullOptional

Additional properties are not allowed.

Fields and variants

json_schemaobject | nullOptional: Additional properties are allowed.
messagestring | nullOptional

sessionobjectRequired

Additional properties are not allowed.

Fields and variants

budgetobjectOptional

Additional properties are not allowed.

Fields and variants

daynumber | nullOptional
monthnumber | nullOptional
sessionnumber | nullOptional
weeknumber | nullOptional

environmentstring | objectOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

computeobjectOptional

Additional properties are not allowed.

Fields and variants

cpuinteger | nullOptional

Minimum: 2. Maximum: 32.

memorystring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

gbinteger | nullOptional: Minimum: 0.
mbinteger | nullOptional: Minimum: 0.

timeoutstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

hoursinteger | nullOptional: Minimum: 0.
minutesinteger | nullOptional: Minimum: 0.
secondsinteger | nullOptional: Minimum: 0.

hooksobjectOptional

Additional properties are not allowed.

Fields and variants

post_clonestring | nullOptional
post_startstring | nullOptional

imageobjectOptional

Additional properties are not allowed.

Fields and variants

dockerfile_appendstring | nullOptional
setupstring | nullOptional

mcp_serversarray<string | object>Optional

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

namestringRequired

variant 3object

Additional properties are not allowed.

Fields and variants

argsarray<string>Optional

Fields and variants

[]string

commandstringRequired

envobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

variant 4object

Additional properties are not allowed.

Fields and variants

headersobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

urlstringRequired

repositoriesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variablesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
valuestring | nullOptional

harnessobjectRequired

The explicitly selected harness and its native options. Matches exactly one variant below.

Fields and variants

type = "claude_code"object

Additional properties are not allowed.

Fields and variants

typestringRequired

Must be "claude_code".

effortstring | nullOptional

Allowed values: "low", "medium", "high", "xhigh", "max".

fallback_modelstring | nullOptional

max_turnsinteger | nullOptional

Greater than: 0.

modelstring | nullOptional

settingsobject | nullOptional

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

type = "codex"object

Additional properties are not allowed.

Fields and variants

typestringRequired: Must be "codex".
effortstring | nullOptional: Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringOptional

instructionsstring | object | array<string | object>Optional

Instructions appended to the harness's own prompt. Text and repository file references are resolved in order. Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

outputobject | nullOptional

Additional properties are not allowed.

Fields and variants

json_schemaobjectRequired: Additional properties are allowed.

permissionsobjectOptional

Additional properties are not allowed.

Fields and variants

ellipsisany JSON value | objectOptional

Matches at least one variant below.

Fields and variants

variant 1any JSON value

Allowed values: true, "all".

variant 2object

Fields and variants

[key]string | object | array<string | object>

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

githubobjectOptional

Additional properties are not allowed.

Fields and variants

permissionsstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

Must be "read_only".

variant 2object

Additional properties are allowed.

Fields and variants

[key]string

repositoriesarray<string> | nullOptional

Fields and variants

[]string

skillsarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

triggerobject | nullOptional

Matches exactly one variant below.

Fields and variants

type = "cron"object

Additional properties are not allowed.

Fields and variants

typestringOptional: Must be "cron".
schedulestringRequired

type = "react"object

Additional properties are not allowed.

Fields and variants

typestringOptional

Must be "react".

issueobject | nullOptional

Additional properties are not allowed.

Fields and variants

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

labelsarray<string>Optional

Fields and variants

[]string

onarray<string>Required

Fields and variants

[]string: Allowed values: "opened", "closed", "commented".

repositoriesobject | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string>Optional

Fields and variants

[]string

variant 2array<string>

Fields and variants

[]string

linear_issueobject | nullOptional

Additional properties are not allowed.

Fields and variants

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

onarray<string>Optional

Fields and variants

[]string: Allowed values: "opened".

pull_requestobject | nullOptional

Additional properties are not allowed.

Fields and variants

basearray<string>Optional

Fields and variants

[]string

draftboolean | nullOptional

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

headarray<string>Optional

Fields and variants

[]string

labelsarray<string>Optional

Fields and variants

[]string

onarray<string>Required

Fields and variants

[]string: Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented".

pathsarray<string>Optional

Fields and variants

[]string

repositoriesobject | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string>Optional

Fields and variants

[]string

variant 2array<string>

Fields and variants

[]string

pushobject | nullOptional

Additional properties are not allowed.

Fields and variants

brancharray<string>Optional

Fields and variants

[]string

forobjectOptional

Additional properties are not allowed.

Fields and variants

botsobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

usersobject | boolean | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string> | booleanOptional

Matches at least one variant below.

Fields and variants

variant 1array<string>

Fields and variants

[]string

variant 2boolean

variant 3array<string>

Fields and variants

[]string

pathsarray<string>Optional

Fields and variants

[]string

repositoriesobject | array<string>Optional

Matches at least one variant below.

Fields and variants

variant 1object

Fields and variants

excludearray<string>Optional

Fields and variants

[]string

includearray<string>Optional

Fields and variants

[]string

variant 2array<string>

Fields and variants

[]string

sentryobject | nullOptional

Additional properties are not allowed.

Fields and variants

onarray<string>Required

Fields and variants

[]string: Allowed values: "issue_alert", "metric_alert".

projectsarray<string>Optional

Fields and variants

[]string

slack_channelobject | nullOptional

Additional properties are not allowed.

idstring | nullOptional

budgetobjectRequired

The spend budget enforced for this session. Additional properties are allowed.

Fields and variants

sourcestringOptional: Where the resolved budget came from. Allowed values: "system", "account", "config", "run".
centsintegerOptional: The spend budget resolved for this session, in cents.

configobjectRequired

What the session ran on, frozen when it was created: the harness block, the resolved environment, permissions, skills, output contract, and budget. Additional properties are not allowed.

Fields and variants

budgetobjectOptional

Additional properties are not allowed.

Fields and variants

daynumber | nullOptional
monthnumber | nullOptional
sessionnumber | nullOptional
weeknumber | nullOptional

environmentstring | objectOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

computeobjectOptional

Additional properties are not allowed.

Fields and variants

cpuinteger | nullOptional

Minimum: 2. Maximum: 32.

memorystring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

gbinteger | nullOptional: Minimum: 0.
mbinteger | nullOptional: Minimum: 0.

timeoutstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

hoursinteger | nullOptional: Minimum: 0.
minutesinteger | nullOptional: Minimum: 0.
secondsinteger | nullOptional: Minimum: 0.

hooksobjectOptional

Additional properties are not allowed.

Fields and variants

post_clonestring | nullOptional
post_startstring | nullOptional

imageobjectOptional

Additional properties are not allowed.

Fields and variants

dockerfile_appendstring | nullOptional
setupstring | nullOptional

mcp_serversarray<string | object>Optional

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

namestringRequired

variant 3object

Additional properties are not allowed.

Fields and variants

argsarray<string>Optional

Fields and variants

[]string

commandstringRequired

envobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

variant 4object

Additional properties are not allowed.

Fields and variants

headersobjectOptional

Additional properties are allowed.

Fields and variants

[key]string

namestringRequired

urlstringRequired

repositoriesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variablesarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

namestringRequired
valuestring | nullOptional

harnessobjectRequired

The explicitly selected harness and its native options. Matches exactly one variant below.

Fields and variants

type = "claude_code"object

Additional properties are not allowed.

Fields and variants

typestringRequired

Must be "claude_code".

effortstring | nullOptional

Allowed values: "low", "medium", "high", "xhigh", "max".

fallback_modelstring | nullOptional

max_turnsinteger | nullOptional

Greater than: 0.

modelstring | nullOptional

settingsobject | nullOptional

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

type = "codex"object

Additional properties are not allowed.

Fields and variants

typestringRequired: Must be "codex".
effortstring | nullOptional: Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringOptional

instructionsstring | object | array<string | object>Optional

Instructions appended to the harness's own prompt. Text and repository file references are resolved in order. Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

variant 2object

Additional properties are not allowed.

Fields and variants

filestringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

outputobject | nullOptional

Additional properties are not allowed.

Fields and variants

json_schemaobjectRequired: Additional properties are allowed.

permissionsobjectOptional

Additional properties are not allowed.

Fields and variants

ellipsisany JSON value | objectOptional

Matches at least one variant below.

Fields and variants

variant 1any JSON value

Allowed values: true, "all".

variant 2object

Fields and variants

[key]string | object | array<string | object>

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

variant 3array<string | object>

Fields and variants

[]string | object

Matches at least one variant below.

Fields and variants

variant 1string

Allowed values: "read", "write", "delete".

variant 2object

Additional properties are not allowed.

Fields and variants

levelstringRequired

Allowed values: "read", "write", "delete".

matcharray<string> | nullOptional

Fields and variants

[]string

githubobjectOptional

Additional properties are not allowed.

Fields and variants

permissionsstring | object | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

Must be "read_only".

variant 2object

Additional properties are allowed.

Fields and variants

[key]string

repositoriesarray<string> | nullOptional

Fields and variants

[]string

skillsarray<object>Optional

Fields and variants

[]object

Additional properties are not allowed.

Fields and variants

pathstringRequired

repositoryobject | nullOptional

Additional properties are not allowed.

Fields and variants

namestringRequired
ownerstring | nullOptional
refstring | nullOptional

context_repositorystring | nullRequired

The "owner/name" repository context the session was started in, if any.

costobjectRequired

What the session cost, in millicents, broken down by leg and carrying its own total. Additional properties are allowed.

Fields and variants

feeintegerOptional: Platform fee in millicents.
llmintegerOptional: LLM spend in millicents.
sandbox_cpuintegerOptional: Sandbox CPU spend in millicents.
sandbox_memoryintegerOptional: Sandbox memory spend in millicents.
totalintegerOptional: The grand total in millicents: llm + sandbox_cpu + sandbox_memory + fee.

created_atstringRequired

When the session was created. Format: date-time.

environmentobjectRequired

The environment the session resolved: the saved environment's id and how it was chosen. The environment's frozen body is `config.environment`. Additional properties are allowed.

Fields and variants

sourcestring | nullOptional: How the environment was chosen (request, automation, platform_default; repo_default and account_default on sessions from before those ladders were removed). Null when the config carried its own inline environment. Allowed values: "request", "automation", "repo_default", "account_default", "platform_default".
environment_idstring | nullOptional: Identifier of the saved environment the session's config resolved. Null for an inline environment block or the built-in basic sandbox.

exit_statusstring | nullRequired

gitobject | nullRequired

Fields and variants

reposarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

commitsarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

committed_atstringRequired: Format: date-time.
pushedbooleanRequired
shastringRequired
subjectstringRequired

commits_totalintegerOptional

full_namestringRequired

local_commitstring | nullOptional

local_uncommitted_filesarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

additionsintegerRequired
deletionsintegerRequired
pathstringRequired
statusstringRequired

prsarray<object>Optional

Fields and variants

[]object

Additional properties are allowed.

Fields and variants

gh_pr_idinteger | nullOptional
numberintegerRequired
titlestring | nullOptional
urlstringRequired

remote_branchstring | nullOptional

remote_commitstring | nullOptional

harnessstringRequired

The coding-agent harness the session runs on. Allowed values: "claude_code", "codex".

idstringRequired

Unique identifier of the session.

last_activity_atstring | nullRequired

When the session last showed activity. Format: date-time.

last_message_atstring | nullRequired

When the session last received a message. Format: date-time.

metadataobjectRequired

Caller-supplied metadata key-value pairs. Additional properties are allowed.

Fields and variants

[key]string

parentobjectRequired

What preceded this session, if anything. Additional properties are allowed.

Fields and variants

kindstring | nullOptional: How this session relates to its parent session, if any. Allowed values: "continuation", "resume".
replayed_from_session_idstring | nullOptional: Identifier of the original session this one was replayed from, if it was started via replay.
session_idstring | nullOptional: Identifier of the parent session that spawned this one, if any.

promptstring | nullRequired

The per-session prompt the session was started with.

promptingobjectRequired

Whether a client may send this session a message and, when it may not, the reason to show instead of a composer. Additional properties are allowed.

Fields and variants

blocked_reasonstring | nullOptional: Allowed values: "mention_surface", "ephemeral_trigger", "non_interactive", "harness_single_turn", "closed".
detailstring | nullOptional
enabledbooleanRequired
surface_namestring | nullOptional

session_statestring | nullRequired

Lifecycle state of the durable conversation, or null for sessions without one. Allowed values: "idle", "running", "closed".

statusstringRequired

Execution status of the session. Allowed values: "scheduled", "creating_sandbox", "running", "retrying", "completed", "error", "cancelled", "stopped".

status_reasonstring | nullRequired

Human-readable reason for the current status, when there is one.

stoppedobjectRequired

The stop request, if the session was stopped. Additional properties are allowed.

Fields and variants

atstring | nullOptional

When a stop was requested, if one was. Format: date-time.

byinteger | nullOptional

GitHub account id of the user who stopped the session, if known.

by_userobject | nullOptional

The GitHub user who stopped the session, resolved at read time. Additional properties are allowed.

Fields and variants

typestringRequired: Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired

summaryobject | nullRequired

The latest live summary of the session's progress while it runs, and when it was generated. Additional properties are allowed.

Fields and variants

created_atstring | nullOptional: When this summary line was generated. Null on summaries written before generation time was tracked. Format: date-time.
descriptionstringRequired: One-line description of what the session is working on.

surfaceobjectRequired

The public status projection: the durable conversation (`session`), the current execution (`run`), and the one derived `status` word. Additional properties are allowed.

Fields and variants

runstring | nullRequired: Allowed values: "scheduled", "starting", "working", "waiting", "done", "failed", "stopped", "cancelled", "retrying".
sessionstring | nullRequired: Allowed values: "alive", "idle", "closed".
statusstring | nullRequired

tokensobjectRequired

The tokens the session spent and the model they went to. `total` includes the prompt-cache lanes. Additional properties are allowed.

Fields and variants

cache_creationintegerOptional: Tokens written to the prompt cache.
cache_readintegerOptional: Tokens read from the prompt cache.
inputintegerOptional: Input tokens used.
modelstringOptional: The model the token counts are attributed to.
outputintegerOptional: Output tokens used.
totalintegerOptional: Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on.

triggerobject | nullRequired

The external event that started the session. Additional properties are allowed.

Fields and variants

actionstring | nullOptional

actorobject | nullOptional

Additional properties are allowed.

Fields and variants

avatar_urlstring | nullOptional
is_botbooleanOptional
namestringRequired

branchstring | nullOptional

numberinteger | nullOptional

repositorystring | nullOptional

surfacestring | nullOptional

titlestring | nullOptional

urlstring | nullOptional

updated_atstringRequired

When the session was last updated. Format: date-time.

deltaStreams an ephemeral text fragment or response output-token count, superseded by the completed record.

Link to this event

Example JSON

{
  "type": "delta",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "kind": "text",
  "text": "All 12 tests",
  "output_tokens": 4
}

Field specification

typestringRequired: Must be "delta".
kindstringRequired: What the partial text is. Known values: text ('thinking' reserved). Open vocabulary: ignore deltas with unknown kinds.
agent_turn_idstring | nullRequired: Identifier of the turn the delta belongs to, if known.
output_tokensinteger | nullRequired: Output tokens generated so far for the current response.
session_execution_idstring | nullRequired: Execution producing this live output.
textstring | nullRequired: The partial output text.

heartbeatKeeps an otherwise idle connection alive, normally after 20 seconds without other updates.

Link to this event

Example JSON

{
  "type": "heartbeat",
  "ts": "2026-09-10T14:00:00Z"
}

Field specification

typestringRequired: Must be "heartbeat".
tsstringRequired: Server time when the heartbeat was sent. Format: date-time.

doneMarks the end of the conversation after the final records and state updates, followed by a normal socket close.

Link to this event

Example JSON

{
  "type": "done"
}

Field specification

typestringRequired: Must be "done".

errorReports a stream-server failure before the socket closes.

Link to this event

Example JSON

{
  "type": "error",
  "message": "Something went wrong streaming this session."
}

Field specification

typestringRequired: Must be "error".
messagestringRequired: A human-readable error message.

delta.kind currently uses text; thinking is reserved. A delta can carry only text or only an output-token count, with the other field null. Deltas have no resume cursor and can be missed across reconnects; render the completed record as the authority.

A parked conversation can remain connected without a done frame. For durable conversations, done follows closure, not each completed turn or idle period. Older sessions without a conversation state finish streaming when their execution reaches a terminal status.

Historical formats

Existing history keeps its original payload format. These examples cover compatibility when reading or replaying older sessions; new executions use the formats above.

Claude SDK records

kind: "claude_sdk" and record_format: "claude_sdk@1" identify historical Claude projections. Their payload discriminator is kind, rather than native type.

systemReports historical harness metadata through subtype and data.

Link to this event

Example JSON

{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "system",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "system",
    "subtype": "init",
    "data": {
      "model": "claude-sonnet-5"
    },
    "session_id": "11111111-1111-4111-8111-111111111111"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_sdk".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_sdk@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

kindstringRequired: Must be "system".
dataobjectOptional: Additional properties are allowed.
session_idstring | nullOptional
subtypestringRequired
uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

userCarries a historical user prompt or tool-result content.

Link to this event

Example JSON

{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "user",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "user",
    "content": "Run the tests and report failures."
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_sdk".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_sdk@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

kindstringRequired

Must be "user".

contentstring | array<object>Required

Matches at least one variant below.

Fields and variants

variant 1string

variant 2array<object>

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "text".
textstringRequired

type = "thinking"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "thinking".
signaturestringRequired
thinkingstringRequired

type = "tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "tool_result".

contentstring | array<object> | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2array<object>

Fields and variants

[]object: Additional properties are allowed.

is_errorboolean | nullOptional

tool_use_idstringRequired

type = "server_tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "server_tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_result".
contentobjectOptional: Additional properties are allowed.
tool_use_idstringRequired

parent_tool_use_idstring | nullOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

assistantCarries historical assistant content with its model at the payload root.

Link to this event

Example JSON

{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "assistant",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "assistant",
    "model": "claude-sonnet-5",
    "content": [
      {
        "type": "text",
        "text": "All 12 tests passed."
      }
    ]
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": "claude-sonnet-5",
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_sdk".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_sdk@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

kindstringRequired

Must be "assistant".

cache_creationobject | nullOptional

Additional properties are not allowed.

Fields and variants

ephemeral_1h_input_tokensintegerOptional
ephemeral_5m_input_tokensintegerOptional

contentarray<object>Optional

Fields and variants

[]object

Matches exactly one variant below.

Fields and variants

type = "text"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "text".
textstringRequired

type = "thinking"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "thinking".
signaturestringRequired
thinkingstringRequired

type = "tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "tool_result".

contentstring | array<object> | nullOptional

Matches at least one variant below.

Fields and variants

variant 1string

variant 2array<object>

Fields and variants

[]object: Additional properties are allowed.

is_errorboolean | nullOptional

tool_use_idstringRequired

type = "server_tool_use"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_use".
idstringRequired
inputobjectOptional: Additional properties are allowed.
namestringRequired

type = "server_tool_result"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "server_tool_result".
contentobjectOptional: Additional properties are allowed.
tool_use_idstringRequired

errorstring | nullOptional

message_idstring | nullOptional

modelstringRequired

parent_tool_use_idstring | nullOptional

session_idstring | nullOptional

stop_reasonstring | nullOptional

usageobject | nullOptional

Additional properties are allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

resultReports a historical turn outcome with cost_usd rather than the native total_cost_usd field.

Link to this event

Example JSON

{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "result",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "result",
    "subtype": "success",
    "is_error": false,
    "num_turns": 1,
    "duration_ms": 4200,
    "duration_api_ms": 3100,
    "result": "All 12 tests passed.",
    "cost_usd": 0.01
  },
  "tools": null,
  "tokens_info": null,
  "cost": 1000,
  "duration": 4200,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_sdk".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_sdk@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

kindstringRequired

Must be "result".

api_error_statusinteger | nullOptional

cost_usdnumber | nullOptional

duration_api_msintegerRequired

duration_msintegerRequired

errorsarray<string> | nullOptional

Fields and variants

[]string

is_errorbooleanRequired

model_usageobject | nullOptional

Additional properties are allowed.

num_turnsintegerRequired

resultstring | nullOptional

session_idstring | nullOptional

stop_reasonstring | nullOptional

structured_outputany JSON valueOptional

subtypestringRequired

usageobject | nullOptional

Additional properties are allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

rate_limitReports historical rate-limit information with snake_case fields.

Link to this event

Example JSON

{
  "kind": "claude_sdk",
  "source": "claude_code",
  "record_format": "claude_sdk@1",
  "record_type": "rate_limit",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "kind": "rate_limit",
    "status": "allowed",
    "rate_limit_type": "five_hour",
    "utilization": 0.25,
    "resets_at": 1789066800
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "claude_sdk".

sourcestringRequired

Must be "claude_code".

record_formatstringRequired

Must be "claude_sdk@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

kindstringRequired: Must be "rate_limit".
rate_limit_typestring | nullOptional
resets_atinteger | nullOptional
session_idstring | nullOptional
statusstringRequired
utilizationnumber | nullOptional
uuidstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

Codex JSONL records

kind: "codex" and record_format: "codex_jsonl@1" identify historical Codex events. Their names use dots, and the payload discriminator is type.

thread.startedAnnounces the historical native thread identifier.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "thread.started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "thread.started",
    "thread_id": "thread_example"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "thread.started".
thread_idstring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn.startedAnnounces a historical native turn beginning.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "turn.started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "turn.started"
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "turn.started".

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

item.startedAnnounces a historical conversation item beginning.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "item.started",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "item.started",
    "item": {
      "id": "command_example",
      "type": "command_execution",
      "command": "pytest -q",
      "status": "in_progress",
      "aggregated_output": ""
    }
  },
  "tools": [
    "Bash"
  ],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "item.started".

itemobjectRequired

Matches exactly one variant below.

Fields and variants

type = "agent_message"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agent_message".
idstring | nullOptional
textstringOptional

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "reasoning".
idstring | nullOptional
summarystring | nullOptional
textstring | nullOptional

type = "command_execution"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "command_execution".
aggregated_outputstring | nullOptional
commandstringOptional
exit_codeinteger | nullOptional
idstring | nullOptional
statusstring | nullOptional

type = "file_change"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "file_change".

changesarray<object> | nullOptional

Fields and variants

[]object: Additional properties are allowed.

idstring | nullOptional

statusstring | nullOptional

type = "mcp_tool_call"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "mcp_tool_call".
idstring | nullOptional
serverstring | nullOptional
statusstring | nullOptional
toolstring | nullOptional

type = "web_search"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "web_search".
idstring | nullOptional
querystring | nullOptional

type = "todo_list"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "todo_list".

idstring | nullOptional

itemsarray<object> | nullOptional

Fields and variants

[]object: Additional properties are allowed.

type = "error"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "error".
idstring | nullOptional
messagestring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

item.updatedSupplies an update to an existing historical item.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "item.updated",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "item.updated",
    "item": {
      "id": "command_example",
      "type": "command_execution",
      "command": "pytest -q",
      "status": "in_progress",
      "aggregated_output": "Running 12 tests..."
    }
  },
  "tools": [
    "Bash"
  ],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "item.updated".

itemobjectRequired

Matches exactly one variant below.

Fields and variants

type = "agent_message"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agent_message".
idstring | nullOptional
textstringOptional

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "reasoning".
idstring | nullOptional
summarystring | nullOptional
textstring | nullOptional

type = "command_execution"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "command_execution".
aggregated_outputstring | nullOptional
commandstringOptional
exit_codeinteger | nullOptional
idstring | nullOptional
statusstring | nullOptional

type = "file_change"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "file_change".

changesarray<object> | nullOptional

Fields and variants

[]object: Additional properties are allowed.

idstring | nullOptional

statusstring | nullOptional

type = "mcp_tool_call"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "mcp_tool_call".
idstring | nullOptional
serverstring | nullOptional
statusstring | nullOptional
toolstring | nullOptional

type = "web_search"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "web_search".
idstring | nullOptional
querystring | nullOptional

type = "todo_list"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "todo_list".

idstring | nullOptional

itemsarray<object> | nullOptional

Fields and variants

[]object: Additional properties are allowed.

type = "error"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "error".
idstring | nullOptional
messagestring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

item.completedSupplies a historical item's completed content or outcome.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "item.completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "item.completed",
    "item": {
      "id": "command_example",
      "type": "command_execution",
      "command": "pytest -q",
      "status": "completed",
      "aggregated_output": "12 passed",
      "exit_code": 0
    }
  },
  "tools": [
    "Bash"
  ],
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "item.completed".

itemobjectRequired

Matches exactly one variant below.

Fields and variants

type = "agent_message"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "agent_message".
idstring | nullOptional
textstringOptional

type = "reasoning"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "reasoning".
idstring | nullOptional
summarystring | nullOptional
textstring | nullOptional

type = "command_execution"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "command_execution".
aggregated_outputstring | nullOptional
commandstringOptional
exit_codeinteger | nullOptional
idstring | nullOptional
statusstring | nullOptional

type = "file_change"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "file_change".

changesarray<object> | nullOptional

Fields and variants

[]object: Additional properties are allowed.

idstring | nullOptional

statusstring | nullOptional

type = "mcp_tool_call"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "mcp_tool_call".
idstring | nullOptional
serverstring | nullOptional
statusstring | nullOptional
toolstring | nullOptional

type = "web_search"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "web_search".
idstring | nullOptional
querystring | nullOptional

type = "todo_list"object

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "todo_list".

idstring | nullOptional

itemsarray<object> | nullOptional

Fields and variants

[]object: Additional properties are allowed.

type = "error"object

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "error".
idstring | nullOptional
messagestring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn.completedReports successful historical turn completion and usage.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "turn.completed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "turn.completed",
    "usage": {
      "input_tokens": 1200,
      "output_tokens": 80,
      "cached_input_tokens": 0
    }
  },
  "tools": null,
  "tokens_info": {
    "input_tokens": 1200,
    "output_tokens": 80,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "num_turns": 0,
    "cost_usd": 0
  },
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired

Must be "turn.completed".

usageobject | nullOptional

Additional properties are allowed.

Fields and variants

cache_write_input_tokensintegerOptional
cached_input_tokensintegerOptional
input_tokensintegerOptional
output_tokensintegerOptional
reasoning_output_tokensintegerOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

turn.failedReports a failed historical turn with its error.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "turn.failed",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "turn.failed",
    "error": {
      "message": "The model request timed out."
    }
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "turn.failed".
errorobject | nullOptional: Additional properties are allowed.

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

errorReports a historical native execution error.

Link to this event

Example JSON

{
  "kind": "codex",
  "source": "codex",
  "record_format": "codex_jsonl@1",
  "record_type": "error",
  "id": "record_example",
  "session_id": "session_example",
  "session_execution_id": "execution_example",
  "agent_turn_id": "turn_example",
  "session_message_id": null,
  "sandbox_id": "sandbox_example",
  "feed_seq": 12,
  "stream_seq": 8,
  "payload": {
    "type": "error",
    "message": "The model request timed out."
  },
  "tools": null,
  "tokens_info": null,
  "cost": null,
  "duration": null,
  "model": null,
  "created_at": "2026-09-10T14:00:00Z"
}

Field specification

kindstringRequired

Must be "codex".

sourcestringRequired

Must be "codex".

record_formatstringRequired

Must be "codex_jsonl@1".

record_typestringRequired

Original record type within its format.

payloadobjectRequired

Additional properties are allowed.

Fields and variants

typestringRequired: Must be "error".
messagestring | nullOptional

agent_turn_idstring | nullRequired

Turn containing this record, when applicable.

costinteger | nullRequired

created_atstringRequired

Format: date-time.

durationinteger | nullRequired

feed_seqintegerRequired

Position in the session feed and the stream's resume cursor.

idstringRequired

Unique identifier of the record.

modelstring | nullRequired

sandbox_idstring | nullRequired

Sandbox that produced this record, when applicable.

session_execution_idstring | nullRequired

Execution that produced the record; null for session-scoped events.

session_idstringRequired

Session containing this record.

session_message_idstring | nullRequired

Message this record receives, delivers, requeues, or echoes.

stream_seqintegerRequired

Position within the execution's stream.

tokens_infoobject | nullRequired

Additional properties are not allowed.

Fields and variants

cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional

toolsarray<string> | nullRequired

Fields and variants

[]string

Unknown records

A record with kind: "unknown" retains its original source, record_format, record_type, and JSON payload. This includes new native methods, new content variants, and payloads that the current typed schema cannot interpret. The additional Codex notifications above show this shape.

Keep unknown records in the ordered feed and advance your cursor past them even if your UI does not render them. Preserve unknown payload fields when storing or relaying events. Ignore unknown outer WebSocket frame types and unknown delta kinds.

For a consumer that renders tool activity, inspect the native message's content blocks or Codex item's type; an unrecognized block or item should not prevent reading the rest of the session.

On this page