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 a message's receipt through environment preparation to the end of its turn.

The session's own event field identifies the external event that started it. The records on this page describe activity throughout that session. See Sessions for source and event fields.

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.

For how the conversation and its turns report progress, and how to know when your message is answered, start with Lifecycle.

Read an event

FieldHow to use it
kindSelect the typed record variant: platform, claude_code, codex_app_server, claude_sdk, codex, or unknown.
sourceIdentify the producer: lifecycle, claude_code, or codex.
record_formatSelect the payload version; existing history retains its original format.
record_typeIdentify the event within its format.
payloadRead the platform fields or the unchanged native message.
feed_seqOrder records within a session and resume the stream after this position.
turn_idCorrelate records with the turn they belong to; environment records carry the turn they prepare for.
session_message_idCorrelate message 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:

1
from ellipsis.models import SessionRecord
2
from ellipsis.frames import StreamFrame
1
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. Every record that belongs to a turn carries its turn_id; environment records carry the turn they prepare for. Older sessions can contain platform record types that are no longer produced; they arrive as unknown records.

message_receivedA message entered the session and its turn was created; turn_id is the turn that will answer it, and closes_session marks a final message.
Link to this event

Use session_message_id to match the message with its native user echo so it renders once. The message is answered when its turn reaches a final status; see Lifecycle.

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "message_received",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": "message_example",
10
"feed_seq": 1,
11
"payload": {
12
"message_id": "message_example",
13
"turn_id": "turn_example",
14
"body": "Run the tests and report failures.",
15
"author": "priya-shah",
16
"sender_attribution_type": "github_user",
17
"sender_attribution_id": "12345",
18
"closes_session": false
19
},
20
"tools": null,
21
"tokens_info": null,
22
"cost": null,
23
"duration": null,
24
"model": null,
25
"created_at": "2026-09-10T14:00:00Z"
26
}

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
turn_idstring | nullOptional
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
environment_phaseA phase of environment preparation started, completed, or failed, with an optional step, timing, and details.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "environment_phase",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 2,
11
"payload": {
12
"phase": "setup",
13
"status": "completed",
14
"step": "after_checkout",
15
"duration_ms": 2400,
16
"detail": null
17
},
18
"tools": null,
19
"tokens_info": null,
20
"cost": null,
21
"duration": null,
22
"model": null,
23
"created_at": "2026-09-10T14:00:03Z"
24
}

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "environment_phase".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
detailobject | nullOptional
Additional properties are allowed.
duration_msinteger | nullOptional
phasestringRequired
statusstringRequired
stepstring | nullOptional
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
environment_outputA chunk of output from environment preparation, including your hooks; many arrive per turn, and chunk orders them within a step.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "environment_output",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 3,
11
"payload": {
12
"phase": "clone",
13
"step": "your-org/api-repo",
14
"stream": "stdout",
15
"chunk": 0,
16
"lines": [
17
"Cloning into 'api-repo'..."
18
]
19
},
20
"tools": null,
21
"tokens_info": null,
22
"cost": null,
23
"duration": null,
24
"model": null,
25
"created_at": "2026-09-10T14:00:01Z"
26
}

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "environment_output".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
chunkintegerRequired
linesarray<string>Required
Fields and variants
[]string
phasestringRequired
stepstring | nullOptional
streamstringOptional
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
environment_readyThe environment is prepared for the listed repositories and the agent is about to start.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "environment_ready",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 4,
11
"payload": {
12
"repositories": [
13
"your-org/api-repo"
14
],
15
"duration_ms": 8400
16
},
17
"tools": null,
18
"tokens_info": null,
19
"cost": null,
20
"duration": null,
21
"model": null,
22
"created_at": "2026-09-10T14:00:08Z"
23
}

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "environment_ready".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
duration_msinteger | nullOptional
repositoriesarray<string>Required
Fields and variants
[]string
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn_startedThe agent started on the turn's message; the turn is now running.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "turn_started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 5,
11
"payload": {
12
"turn_id": "turn_example",
13
"turn_index": 0
14
},
15
"tools": null,
16
"tokens_info": null,
17
"cost": null,
18
"duration": null,
19
"model": null,
20
"created_at": "2026-09-10T14:00:09Z"
21
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
message_deliveredThe agent started on the message, on the identified turn.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "message_delivered",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": "message_example",
10
"feed_seq": 6,
11
"payload": {
12
"message_id": "message_example",
13
"turn_id": "turn_example"
14
},
15
"tools": null,
16
"tokens_info": null,
17
"cost": null,
18
"duration": null,
19
"model": null,
20
"created_at": "2026-09-10T14:00:09Z"
21
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn_endedThe turn reached its final status; status, reason, and detail match the turn on the session object.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "turn_ended",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 7,
11
"payload": {
12
"turn_id": "turn_example",
13
"turn_index": 0,
14
"status": "completed",
15
"reason": null,
16
"detail": null,
17
"duration_ms": 4200
18
},
19
"tools": null,
20
"tokens_info": null,
21
"cost": null,
22
"duration": null,
23
"model": null,
24
"created_at": "2026-09-10T14:00:13Z"
25
}

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "turn_ended".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
detailstring | nullOptional
duration_msinteger | nullOptional
reasonstring | nullOptional
statusstringRequired
turn_idstringRequired
turn_indexintegerRequired
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
message_requeuedThe turn ended before answering the message, so the message was queued again with a new pending turn, requeued_turn_id.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "message_requeued",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_requeued_example",
9
"session_message_id": "message_example",
10
"feed_seq": 8,
11
"payload": {
12
"message_id": "message_example",
13
"turn_id": "turn_example",
14
"requeued_turn_id": "turn_requeued_example"
15
},
16
"tools": null,
17
"tokens_info": null,
18
"cost": null,
19
"duration": null,
20
"model": null,
21
"created_at": "2026-09-10T14:00:13Z"
22
}

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
requeued_turn_idstring | nullOptional
turn_idstringRequired
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
session_closedThe conversation closed permanently, after the turn of a session that runs once or after a closing message's turn.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "session_closed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": null,
9
"session_message_id": null,
10
"feed_seq": 10,
11
"payload": {},
12
"tools": null,
13
"tokens_info": null,
14
"cost": null,
15
"duration": null,
16
"model": null,
17
"created_at": "2026-09-10T14:00:14Z"
18
}

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.
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.

environment_phase.phase names a stage of preparation: image (the base image), clone (the repositories), setup (the environment's build_base and after_checkout hooks, named in step), snapshot (saving the prepared environment for reuse), restore (bringing a saved environment back for a later turn), and hooks (the before_start hook, which runs each time an environment is prepared, before the agent starts). status is started, completed, or failed. Phases, steps, and statuses are open vocabularies, so render values you don't recognize as they are. environment_output carries the same phase and step; a clone chunk names the repository in step. A reused environment skips its build steps.

A turn's status, reason, and detail also arrive on the session frame; turn_ended is the record of the same change. There are no separate session-level success, failure, or stop records: the conversation reports only session_closed.

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

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "system",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "system",
13
"subtype": "init",
14
"model": "claude-opus-5-5",
15
"tools": [
16
"Bash",
17
"Read"
18
],
19
"cwd": "/workspace",
20
"session_id": "11111111-1111-4111-8111-111111111111",
21
"uuid": "22222222-2222-4222-8222-222222222222"
22
},
23
"tools": null,
24
"tokens_info": null,
25
"cost": null,
26
"duration": null,
27
"model": null,
28
"created_at": "2026-09-10T14:00:00Z"
29
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
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

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "system",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "system",
13
"subtype": "vcs_state_changed",
14
"kind": "push",
15
"cwd": "/workspace",
16
"session_id": "11111111-1111-4111-8111-111111111111",
17
"uuid": "22222222-2222-4222-8222-222222222222"
18
},
19
"tools": null,
20
"tokens_info": null,
21
"cost": null,
22
"duration": null,
23
"model": null,
24
"created_at": "2026-09-10T14:00:00Z"
25
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
userCarries a user-message echo or tool results supplied back to Claude; this example is a tool result.
Link to this event

Example JSON

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "user",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "user",
13
"message": {
14
"role": "user",
15
"content": [
16
{
17
"type": "tool_result",
18
"tool_use_id": "tool_example",
19
"content": "12 passed",
20
"is_error": false
21
}
22
]
23
},
24
"parent_tool_use_id": null,
25
"session_id": "11111111-1111-4111-8111-111111111111",
26
"uuid": "22222222-2222-4222-8222-222222222222"
27
},
28
"tools": null,
29
"tokens_info": null,
30
"cost": null,
31
"duration": null,
32
"model": null,
33
"created_at": "2026-09-10T14:00:00Z"
34
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
assistantCarries completed assistant content, including text, thinking, and tool calls.
Link to this event

Example JSON

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "assistant",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "assistant",
13
"message": {
14
"type": "message",
15
"role": "assistant",
16
"id": "message_native",
17
"model": "claude-opus-5-5",
18
"content": [
19
{
20
"type": "text",
21
"text": "I will run the tests."
22
},
23
{
24
"type": "tool_use",
25
"id": "tool_example",
26
"name": "Bash",
27
"input": {
28
"command": "pytest -q"
29
}
30
}
31
],
32
"usage": {
33
"input_tokens": 1200,
34
"output_tokens": 80,
35
"cache_read_input_tokens": 0,
36
"cache_creation_input_tokens": 0
37
},
38
"stop_reason": "tool_use"
39
},
40
"parent_tool_use_id": null,
41
"session_id": "11111111-1111-4111-8111-111111111111",
42
"uuid": "22222222-2222-4222-8222-222222222222"
43
},
44
"tools": [
45
"Bash"
46
],
47
"tokens_info": {
48
"input_tokens": 1200,
49
"output_tokens": 80,
50
"cache_read_input_tokens": 0,
51
"cache_creation_input_tokens": 0,
52
"num_turns": 0,
53
"cost_usd": 0
54
},
55
"cost": null,
56
"duration": null,
57
"model": "claude-opus-5-5",
58
"created_at": "2026-09-10T14:00:00Z"
59
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
rate_limitReports rate-limit status and reset information; the native payload names the event rate_limit_event.
Link to this event

Example JSON

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "rate_limit",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "rate_limit_event",
13
"rate_limit_info": {
14
"status": "allowed",
15
"rateLimitType": "five_hour",
16
"utilization": 0.25,
17
"resetsAt": 1789066800
18
},
19
"session_id": "11111111-1111-4111-8111-111111111111",
20
"uuid": "22222222-2222-4222-8222-222222222222"
21
},
22
"tools": null,
23
"tokens_info": null,
24
"cost": null,
25
"duration": null,
26
"model": null,
27
"created_at": "2026-09-10T14:00:00Z"
28
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
resultReports a harness turn outcome with its output, elapsed time, usage, and reported cost.
Link to this event

Example JSON

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "result",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "result",
13
"subtype": "success",
14
"is_error": false,
15
"num_turns": 1,
16
"duration_ms": 4200,
17
"duration_api_ms": 3100,
18
"result": "All 12 tests passed.",
19
"total_cost_usd": 0.01,
20
"usage": {
21
"input_tokens": 1200,
22
"output_tokens": 80,
23
"cache_read_input_tokens": 0,
24
"cache_creation_input_tokens": 0
25
},
26
"session_id": "11111111-1111-4111-8111-111111111111",
27
"uuid": "22222222-2222-4222-8222-222222222222"
28
},
29
"tools": null,
30
"tokens_info": {
31
"input_tokens": 1200,
32
"output_tokens": 80,
33
"cache_read_input_tokens": 0,
34
"cache_creation_input_tokens": 0,
35
"num_turns": 0,
36
"cost_usd": 0
37
},
38
"cost": 1000,
39
"duration": 4200,
40
"model": null,
41
"created_at": "2026-09-10T14:00:00Z"
42
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
conversation_resetReports that Claude switched to a new native conversation identifier.
Link to this event

Example JSON

1
{
2
"kind": "claude_code",
3
"source": "claude_code",
4
"record_format": "claude_jsonl@1",
5
"record_type": "conversation_reset",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "conversation_reset",
13
"new_conversation_id": "33333333-3333-4333-8333-333333333333",
14
"session_id": "11111111-1111-4111-8111-111111111111",
15
"uuid": "22222222-2222-4222-8222-222222222222"
16
},
17
"tools": null,
18
"tokens_info": null,
19
"cost": null,
20
"duration": null,
21
"model": null,
22
"created_at": "2026-09-10T14:00:00Z"
23
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.

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

1
{
2
"kind": "unknown",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "remoteControl/status/changed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": null,
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "remoteControl/status/changed",
13
"params": {
14
"status": "disabled",
15
"serverName": "sandbox",
16
"installationId": "installation_example",
17
"environmentId": null
18
}
19
},
20
"tools": null,
21
"tokens_info": null,
22
"cost": null,
23
"duration": null,
24
"model": null,
25
"created_at": "2026-09-10T14:00:00Z"
26
}

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.
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
thread/startedAnnounces the native thread and its metadata.
Link to this event

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "thread/started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "thread/started",
13
"params": {
14
"thread": {
15
"id": "thread_example",
16
"cliVersion": "0.160.0",
17
"modelProvider": "openai",
18
"cwd": "/workspace/api-repo",
19
"turns": []
20
}
21
}
22
},
23
"tools": null,
24
"tokens_info": null,
25
"cost": null,
26
"duration": null,
27
"model": null,
28
"created_at": "2026-09-10T14:00:00Z"
29
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
thread/status/changedReports native thread activity, such as becoming active or idle, as an unknown record.
Link to this event

Example JSON

1
{
2
"kind": "unknown",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "thread/status/changed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": null,
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "thread/status/changed",
13
"params": {
14
"threadId": "thread_example",
15
"status": {
16
"type": "idle"
17
}
18
}
19
},
20
"tools": null,
21
"tokens_info": null,
22
"cost": null,
23
"duration": null,
24
"model": null,
25
"created_at": "2026-09-10T14:00:00Z"
26
}

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.
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn/startedAnnounces the start of a native turn.
Link to this event

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "turn/started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "turn/started",
13
"params": {
14
"threadId": "thread_example",
15
"turn": {
16
"id": "native_turn_example",
17
"status": "inProgress",
18
"items": [],
19
"error": null
20
}
21
}
22
},
23
"tools": null,
24
"tokens_info": null,
25
"cost": null,
26
"duration": null,
27
"model": null,
28
"created_at": "2026-09-10T14:00:00Z"
29
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
item/startedAnnounces the start of a message, command, file change, or another conversation item.
Link to this event

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "item/started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "item/started",
13
"params": {
14
"threadId": "thread_example",
15
"turnId": "native_turn_example",
16
"item": {
17
"type": "commandExecution",
18
"id": "command_example",
19
"command": "pytest -q",
20
"cwd": "/workspace/api-repo",
21
"commandActions": [],
22
"status": "inProgress"
23
}
24
}
25
},
26
"tools": [
27
"Bash"
28
],
29
"tokens_info": null,
30
"cost": null,
31
"duration": null,
32
"model": null,
33
"created_at": "2026-09-10T14:00:00Z"
34
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
item/completedSupplies a completed item, including its content, output, or outcome.
Link to this event

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "item/completed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "item/completed",
13
"params": {
14
"threadId": "thread_example",
15
"turnId": "native_turn_example",
16
"item": {
17
"type": "commandExecution",
18
"id": "command_example",
19
"command": "pytest -q",
20
"cwd": "/workspace/api-repo",
21
"commandActions": [],
22
"status": "completed",
23
"aggregatedOutput": "12 passed",
24
"exitCode": 0,
25
"durationMs": 4200
26
}
27
}
28
},
29
"tools": [
30
"Bash"
31
],
32
"tokens_info": null,
33
"cost": null,
34
"duration": null,
35
"model": null,
36
"created_at": "2026-09-10T14:00:00Z"
37
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
thread/tokenUsage/updatedReports cumulative native thread usage and usage for the latest model call.
Link to this event

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "thread/tokenUsage/updated",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "thread/tokenUsage/updated",
13
"params": {
14
"threadId": "thread_example",
15
"turnId": "native_turn_example",
16
"tokenUsage": {
17
"total": {
18
"inputTokens": 1200,
19
"outputTokens": 80,
20
"cachedInputTokens": 0,
21
"reasoningOutputTokens": 0,
22
"totalTokens": 1280
23
},
24
"last": {
25
"inputTokens": 1200,
26
"outputTokens": 80,
27
"cachedInputTokens": 0,
28
"reasoningOutputTokens": 0,
29
"totalTokens": 1280
30
},
31
"modelContextWindow": 272000
32
}
33
}
34
},
35
"tools": null,
36
"tokens_info": {
37
"input_tokens": 1200,
38
"output_tokens": 80,
39
"cache_read_input_tokens": 0,
40
"cache_creation_input_tokens": 0,
41
"num_turns": 0,
42
"cost_usd": 0
43
},
44
"cost": null,
45
"duration": null,
46
"model": null,
47
"created_at": "2026-09-10T14:00:00Z"
48
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
account/rateLimits/updatedReports native account rate-limit information as an unknown record.
Link to this event

Example JSON

1
{
2
"kind": "unknown",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "account/rateLimits/updated",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": null,
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "account/rateLimits/updated",
13
"params": {
14
"rateLimits": {
15
"limitId": "codex",
16
"limitName": null,
17
"primary": null,
18
"secondary": null,
19
"credits": null,
20
"planType": null
21
}
22
}
23
},
24
"tools": null,
25
"tokens_info": null,
26
"cost": null,
27
"duration": null,
28
"model": null,
29
"created_at": "2026-09-10T14:00:00Z"
30
}

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.
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
errorReports a native error and whether Codex intends to retry it.
Link to this event

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "error",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "error",
13
"params": {
14
"threadId": "thread_example",
15
"turnId": "native_turn_example",
16
"error": {
17
"message": "The model request timed out."
18
},
19
"willRetry": true
20
}
21
},
22
"tools": null,
23
"tokens_info": null,
24
"cost": null,
25
"duration": null,
26
"model": null,
27
"created_at": "2026-09-10T14:00:00Z"
28
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn/completedReports a native turn ending with status completed, failed, or interrupted.
Link to this event

Command item/completed notifications can arrive after this native event. For a successful turn, Ellipsis waits up to two seconds for pending command notifications before emitting the platform turn_ended record. Commands left running in the background do not keep the platform turn open indefinitely.

Example JSON

1
{
2
"kind": "codex_app_server",
3
"source": "codex",
4
"record_format": "codex_app_server@1",
5
"record_type": "turn/completed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"method": "turn/completed",
13
"params": {
14
"threadId": "thread_example",
15
"turn": {
16
"id": "native_turn_example",
17
"status": "completed",
18
"items": [],
19
"error": null
20
}
21
}
22
},
23
"tools": null,
24
"tokens_info": null,
25
"cost": null,
26
"duration": null,
27
"model": null,
28
"created_at": "2026-09-10T14:00:00Z"
29
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.

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 with kind: "text". Readable item/reasoning/summaryTextDelta notifications supply kind: "thinking" previews. Each preview replaces the first-line prefix of the current summary section; item/reasoning/summaryPartAdded starts a new section. Raw reasoning deltas are not included in these previews. Native incremental tool and plan 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=6; 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

1
{
2
"type": "snapshot",
3
"protocol": 6,
4
"earliest_feed_seq": 1,
5
"session": {
6
"id": "session_example",
7
"conversation": {
8
"state": "open",
9
"interactive": true,
10
"warm": true,
11
"prompting": {
12
"enabled": true,
13
"blocked_reason": null,
14
"detail": null,
15
"surface_name": null
16
}
17
},
18
"turn": {
19
"id": "turn_example",
20
"index": 0,
21
"status": "running",
22
"reason": null,
23
"detail": null,
24
"stopped": null,
25
"created_at": "2026-09-10T14:00:00Z",
26
"started_at": "2026-09-10T14:00:09Z",
27
"ended_at": null,
28
"cost": {
29
"llm": 0,
30
"cpu": 0,
31
"memory": 0,
32
"fee": 0,
33
"total": 0
34
},
35
"tokens": {
36
"input": 0,
37
"output": 0,
38
"cache_read": 0,
39
"cache_creation": 0,
40
"total": 0,
41
"model": "claude-opus-5-5"
42
}
43
},
44
"archived": null,
45
"created_at": "2026-09-10T14:00:00Z",
46
"updated_at": "2026-09-10T14:00:09Z",
47
"source": "api",
48
"event": null,
49
"cost": {
50
"llm": 0,
51
"cpu": 0,
52
"memory": 0,
53
"fee": 0,
54
"total": 0
55
},
56
"tokens": {
57
"input": 0,
58
"output": 0,
59
"cache_read": 0,
60
"cache_creation": 0,
61
"total": 0,
62
"model": "claude-opus-5-5"
63
},
64
"parent": null,
65
"attribution": {
66
"type": "api_key",
67
"id": "key_example",
68
"user": null
69
},
70
"budget": 3.0,
71
"agent": null,
72
"handler": null,
73
"environment": {
74
"id": null,
75
"source": "platform_default",
76
"repositories": [],
77
"variables": [],
78
"compute": {
79
"cpu": null,
80
"memory": null,
81
"timeout": null
82
},
83
"hooks": {
84
"post_start": null,
85
"post_clone": null,
86
"build_base": null,
87
"after_checkout": null,
88
"before_start": null
89
},
90
"mcp_servers": []
91
},
92
"metadata": {},
93
"git": null,
94
"summary": null,
95
"permissions": {
96
"ellipsis": true,
97
"github": {
98
"permissions": null,
99
"repositories": null
100
}
101
},
102
"skills": [],
103
"output": null,
104
"claude_code": {
105
"model": "claude-opus-5-5",
106
"effort": null,
107
"fallback_model": null,
108
"max_turns": null,
109
"settings": null,
110
"prompt": "Run the tests and report failures."
111
},
112
"codex": null
113
},
114
"messages": []
115
}

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.
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".
turn_idstring | nullRequired
The turn created to answer this message. Wait on it: the message is answered when that turn reaches a final status.
protocolintegerRequired
Echoes the protocol version the server is serving.
sessionobjectRequired
The session's current state. Additional properties are not allowed.
Fields and variants
sourcestringRequired
Where the session came from (e.g. react, web, api, cli, mention, cron). Allowed values: "react", "code_review", "web", "api", "cli", "mention", "cron".
agentobject | nullRequired
The agent 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 agent definition the session was started from, frozen when the session was created. Additional properties are not allowed.
Fields and variants
ellipsisobjectRequired
Additional properties are not allowed.
Fields and variants
kindstringRequired
Must be "agent".
descriptionstring | nullRequired
enabledbooleanRequired
metadataobjectRequired
Additional properties are not allowed.
Fields and variants
annotationsobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
labelsarray<string>Required
Fields and variants
[]string
namestring | nullRequired
versionstringRequired
inputobject | nullRequired
Additional properties are not allowed.
Fields and variants
json_schemaobject | nullRequired
Additional properties are allowed.
messagestring | nullRequired
sessionobjectRequired
Additional properties are not allowed.
Fields and variants
budgetobjectRequired
Additional properties are not allowed.
Fields and variants
daynumber | nullRequired
The most the agent may spend over the last day, in US dollars.
monthnumber | nullRequired
The most the agent may spend over the last 28 days, in US dollars.
sessionnumber | nullRequired
The most one session may spend, in US dollars. Greater than: 0.
weeknumber | nullRequired
The most the agent may spend over the last 7 days, in US dollars.
claude_codeobject | nullRequired
Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Allowed values: "low", "medium", "high", "xhigh", "max".
fallback_modelstring | nullRequired
max_turnsinteger | nullRequired
Greater than: 0.
modelstringRequired
The model the session runs on: an alias or canonical id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
settingsobject | nullRequired
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
codexobject | nullRequired
Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringRequired
The model the session runs on: a Responses-capable id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
conversationobjectRequired
Additional properties are not allowed.
Fields and variants
interactivebooleanRequired
Whether the session stays open after its first turn. Defaults to true; false runs once and requires a prompt. Requires the model's interactive capability when true. Direct message acceptance is reported separately in conversation.prompting.
environmentstring | objectRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
computeobjectRequired
Additional properties are not allowed.
Fields and variants
cpuinteger | nullRequired
Minimum: 2. Maximum: 32.
memorystring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
gbinteger | nullRequired
Minimum: 0.
mbinteger | nullRequired
Minimum: 0.
timeoutstring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
hoursinteger | nullRequired
Minimum: 0.
minutesinteger | nullRequired
Minimum: 0.
secondsinteger | nullRequired
Minimum: 0.
hooksobjectRequired
Additional properties are not allowed.
Fields and variants
after_checkoutobject | string | nullRequired
Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared environment. Skipped when that prepared environment is reused. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
before_startobject | string | nullRequired
Run before the agent starts or resumes a session, after the environment is ready. This hook is not cached and adds to session startup time. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
build_baseobject | string | nullRequired
Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
inputsarray<string> | nullRequired
Exact files relative to the workspace directory `/sandbox`, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files.
Fields and variants
[]string
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
post_clonestring | nullRequired
Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation.
post_startstring | nullRequired
Legacy session startup script. Use before_start in new configurations.
mcp_serversarray<string | object>Required
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>Required
Fields and variants
[]string
commandstringRequired
envobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
variant 4object
Additional properties are not allowed.
Fields and variants
headersobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
urlstringRequired
repositoriesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
variablesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
valuestring | nullRequired
metadataobjectRequired
Arbitrary string key/value metadata stored on every session. Additional properties are allowed.
Fields and variants
[key]string
outputobject | nullRequired
Additional properties are not allowed.
Fields and variants
json_schemaobjectRequired
Additional properties are allowed.
permissionsobjectRequired
Additional properties are not allowed.
Fields and variants
ellipsisany JSON value | objectRequired
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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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> | nullRequired
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> | nullRequired
Fields and variants
[]string
githubobjectRequired
Additional properties are not allowed.
Fields and variants
permissionsstring | object | nullRequired
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> | nullRequired
Fields and variants
[]string
skillsarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
triggerobject | nullRequired
Matches exactly one variant below.
Fields and variants
type = "cron"object
Additional properties are not allowed.
Fields and variants
typestringRequired
Must be "cron".
schedulestringRequired
type = "react"object
Additional properties are not allowed.
Fields and variants
typestringRequired
Must be "react".
check_runobject | nullRequired
Additional properties are not allowed.
Fields and variants
brancharray<string>Required
Fields and variants
[]string
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
namesarray<string>Required
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "failed".
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
issueobject | nullRequired
Additional properties are not allowed.
Fields and variants
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
labelsarray<string>Required
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "opened", "closed", "commented".
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
linear_issueobject | nullRequired
Additional properties are not allowed.
Fields and variants
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "opened".
pull_requestobject | nullRequired
Additional properties are not allowed.
Fields and variants
basearray<string>Required
Fields and variants
[]string
draftboolean | nullRequired
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
headarray<string>Required
Fields and variants
[]string
labelsarray<string>Required
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented".
pathsarray<string>Required
Fields and variants
[]string
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
pushobject | nullRequired
Additional properties are not allowed.
Fields and variants
brancharray<string>Required
Fields and variants
[]string
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
pathsarray<string>Required
Fields and variants
[]string
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
releaseobject | nullRequired
Additional properties are not allowed.
Fields and variants
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "published".
prereleaseboolean | nullRequired
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
tagarray<string>Required
Fields and variants
[]string
sentryobject | nullRequired
Additional properties are not allowed.
Fields and variants
onarray<string>Required
Fields and variants
[]string
Allowed values: "issue_alert", "metric_alert".
projectsarray<string>Required
Fields and variants
[]string
slack_channelobject | nullRequired
Additional properties are not allowed.
idstring | nullRequired
Identifier of the saved agent this session's snapshot was taken from. Null for a routing-file agent or the built-in mention agent, which have no saved agent behind them. Points at the agent as it exists now, which may have changed since.
archivedobject | nullRequired
When and by whom the session was archived; null when unarchived. Archiving does not stop or close a session. Additional properties are allowed.
Fields and variants
atstringRequired
When the session was archived. Format: date-time.
byobject | nullRequired
The GitHub user who archived the session; null if unknown or unavailable. Additional properties are allowed.
Fields and variants
typestringRequired
Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired
namestring | nullRequired
attributionobjectRequired
The principal this session is attributed to. Additional properties are allowed.
Fields and variants
typestring | nullRequired
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 | nullRequired
Identifier of the principal the session is attributed to.
userobject | nullRequired
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
namestring | nullRequired
budgetnumberRequired
The spend budget enforced for this session, in US dollars, after resolving defaults and ceilings.
claude_codeobject | nullRequired
Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Allowed values: "low", "medium", "high", "xhigh", "max".
fallback_modelstring | nullRequired
max_turnsinteger | nullRequired
Greater than: 0.
modelstringRequired
The model the session runs on: an alias or canonical id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
settingsobject | nullRequired
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
codexobject | nullRequired
Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringRequired
The model the session runs on: a Responses-capable id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
conversationobjectRequired
Whether the session can take more messages, and whether an agent is warm to answer one. Additional properties are allowed.
Fields and variants
interactivebooleanRequired
Whether the session stays open after its first turn.
promptingobjectRequired
The session's policy for direct messages. Caller authorization and message validation are checked separately. Additional properties are allowed.
Fields and variants
blocked_reasonstring | nullRequired
Allowed values: "mention_surface", "non_interactive", "harness_single_turn", "budget_exhausted", "closed".
detailstring | nullRequired
enabledbooleanRequired
surface_namestring | nullRequired
statestringRequired
`open` while the session can take messages; `closed` is permanent. Allowed values: "open", "closed".
warmbooleanRequired
Whether an agent is ready to answer the next message right away. When false, the next message first prepares an environment, which takes longer. A hint only; clients need no logic on it.
costobjectRequired
What the session has cost so far, in millicents, broken down by leg and carrying its own total. Additional properties are allowed.
Fields and variants
cpuintegerRequired
CPU spend in millicents.
feeintegerRequired
Platform fee in millicents.
llmintegerRequired
LLM spend in millicents.
memoryintegerRequired
Memory spend in millicents.
totalintegerRequired
The grand total in millicents: llm + cpu + memory + fee.
created_atstringRequired
When the session was created. Format: date-time.
environmentobjectRequired
The full environment configuration frozen when the session was created, with the saved environment's id and how it was chosen. Additional properties are not allowed.
Fields and variants
sourcestring | nullRequired
How the environment was chosen (request, agent, platform_default; repo_default and account_default on sessions from before those ladders were removed). An inline request uses request; an inline environment declared in session configuration has no source. Allowed values: "request", "agent", "repo_default", "account_default", "platform_default".
computeobjectRequired
Additional properties are not allowed.
Fields and variants
cpuinteger | nullRequired
Minimum: 2. Maximum: 32.
memorystring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
gbinteger | nullRequired
Minimum: 0.
mbinteger | nullRequired
Minimum: 0.
timeoutstring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
hoursinteger | nullRequired
Minimum: 0.
minutesinteger | nullRequired
Minimum: 0.
secondsinteger | nullRequired
Minimum: 0.
hooksobjectRequired
Additional properties are not allowed.
Fields and variants
after_checkoutobject | string | nullRequired
Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared environment. Skipped when that prepared environment is reused. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
before_startobject | string | nullRequired
Run before the agent starts or resumes a session, after the environment is ready. This hook is not cached and adds to session startup time. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
build_baseobject | string | nullRequired
Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
inputsarray<string> | nullRequired
Exact files relative to the workspace directory `/sandbox`, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files.
Fields and variants
[]string
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
post_clonestring | nullRequired
Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation.
post_startstring | nullRequired
Legacy session startup script. Use before_start in new configurations.
idstring | nullRequired
Identifier of the saved environment the session's config resolved. Null for an inline environment block or the built-in basic environment.
mcp_serversarray<string | object>Required
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>Required
Fields and variants
[]string
commandstringRequired
envobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
variant 4object
Additional properties are not allowed.
Fields and variants
headersobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
urlstringRequired
repositoriesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
variablesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
valuestring | nullRequired
eventobject | nullRequired
The typed external event that started the session; null for direct and scheduled starts. Matches exactly one variant below.
Fields and variants
type = "github.pull_request"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.pull_request".
actionstringRequired
Matches at least one variant below.
Fields and variants
variant 1string
Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented".
variant 2string
Must be "review_commented".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
branchstringRequired
numberintegerRequired
repositorystringRequired
titlestringRequired
urlstringRequired
type = "github.issue"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.issue".
actionstringRequired
Allowed values: "opened", "closed", "commented".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
numberintegerRequired
repositorystringRequired
titlestringRequired
urlstringRequired
type = "github.push"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.push".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
afterstringRequired
beforestringRequired
branchstringRequired
repositorystringRequired
urlstringRequired
type = "github.check_run"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.check_run".
actionstringRequired
Allowed values: "failed".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
branchstring | nullRequired
conclusionstring | nullRequired
head_shastringRequired
namestringRequired
pull_request_numberinteger | nullRequired
repositorystringRequired
urlstringRequired
type = "github.release"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.release".
actionstringRequired
Allowed values: "published".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
namestring | nullRequired
prereleasebooleanRequired
repositorystringRequired
tagstringRequired
urlstringRequired
type = "linear.issue"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "linear.issue".
actionstringRequired
Matches at least one variant below.
Fields and variants
variant 1string
Allowed values: "opened".
variant 2string
Must be "commented".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
identifierstring | nullRequired
numberintegerRequired
titlestringRequired
urlstringRequired
type = "slack.message"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "slack.message".
actionstringRequired
Allowed values: "message", "app_mention".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
channel_idstringRequired
channel_namestring | nullRequired
message_tsstringRequired
thread_tsstring | nullRequired
urlstringRequired
type = "slack.channel_created"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "slack.channel_created".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
channel_idstringRequired
channel_namestring | nullRequired
urlstringRequired
type = "sentry.alert"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "sentry.alert".
actionstringRequired
Allowed values: "issue_alert", "metric_alert".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
organization_slugstringRequired
project_slugstring | nullRequired
titlestring | nullRequired
urlstring | nullRequired
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>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
commitsarray<object>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
committed_atstringRequired
Format: date-time.
pushedbooleanRequired
shastringRequired
subjectstringRequired
commits_totalintegerRequired
full_namestringRequired
local_commitstring | nullRequired
local_uncommitted_filesarray<object>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
additionsintegerRequired
deletionsintegerRequired
pathstringRequired
statusstringRequired
prsarray<object>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
gh_pr_idinteger | nullRequired
numberintegerRequired
titlestring | nullRequired
urlstringRequired
remote_branchstring | nullRequired
remote_commitstring | nullRequired
handlerobject | nullRequired
The saved handler and its effective display name when this session started, frozen at creation. Null for built-in responders, legacy sessions, and sessions started without a handler. Additional properties are allowed.
Fields and variants
agent_namestringRequired
The handler's effective display name when the session started: ellipsis.name, or the service default (Slack, GitHub, Linear, or sentry).
idstringRequired
Identifier of the saved handler.
servicestringRequired
The service the handler responds to. Allowed values: "slack", "github", "linear", "sentry".
shastringRequired
Content fingerprint of the validated handler configuration used when the session started. This is not the Git commit SHA.
idstringRequired
Unique identifier of the session.
metadataobjectRequired
Caller-supplied metadata key-value pairs. Additional properties are allowed.
Fields and variants
[key]string
outputobject | nullRequired
The structured-output exit contract for this session. Additional properties are not allowed.
Fields and variants
json_schemaobjectRequired
Additional properties are allowed.
parentobject | nullRequired
The predecessor session this session continues; null when there is none. Additional properties are allowed.
Fields and variants
session_idstring | nullRequired
Identifier of the predecessor session this session continues, if any.
permissionsobjectRequired
What the session may touch, per minted credential. Additional properties are not allowed.
Fields and variants
ellipsisany JSON value | objectRequired
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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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> | nullRequired
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> | nullRequired
Fields and variants
[]string
githubobjectRequired
Additional properties are not allowed.
Fields and variants
permissionsstring | object | nullRequired
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> | nullRequired
Fields and variants
[]string
skillsarray<object>Required
Skills installed for this session.
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
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 | nullRequired
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 doing.
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_creationintegerRequired
Tokens written to the prompt cache.
cache_readintegerRequired
Tokens read from the prompt cache.
inputintegerRequired
Input tokens used.
modelstringRequired
The model the token counts are attributed to.
outputintegerRequired
Output tokens used.
totalintegerRequired
Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on.
turnobject | nullRequired
The turn in progress, or the latest one when none is running. Null until the session has a message. Wait on it: the message you sent is answered when the turn with your message's `turn_id` reaches a final status. Additional properties are allowed.
Fields and variants
costobjectRequired
What the turn cost so far, in millicents, broken down by leg. Additional properties are allowed.
Fields and variants
cpuintegerRequired
CPU spend in millicents.
feeintegerRequired
Platform fee in millicents.
llmintegerRequired
LLM spend in millicents.
memoryintegerRequired
Memory spend in millicents.
totalintegerRequired
The grand total in millicents: llm + cpu + memory + fee.
created_atstringRequired
When the turn's message was received. Format: date-time.
detailstring | nullRequired
A human-readable explanation of a failed, stopped, or cancelled turn.
ended_atstring | nullRequired
When the turn reached its final status. Format: date-time.
idstringRequired
Unique identifier of the turn.
indexintegerRequired
Position in the session, starting at 0.
reasonstring | nullRequired
Why the turn failed or was cancelled; null on every other status. Allowed values: "error", "tool_call_failed", "budget_hit", "payment_required", "blocked", "contact_email_required", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_environment_variables", "missing_github_integration", "agent_unavailable", "upstream_unavailable", "unsupported_configuration", "execution_disabled", "interrupted".
started_atstring | nullRequired
When the agent started on the message. Format: date-time.
statusstringRequired
Where the turn is. Allowed values: "pending", "running", "completed", "failed", "stopped", "cancelled".
stoppedobject | nullRequired
When and by whom a stop was requested; null when none was. Additional properties are allowed.
Fields and variants
atstringRequired
When a stop was requested. Format: date-time.
byobject | nullRequired
The GitHub user who stopped the session, resolved at read time. Null if the user is unknown or unavailable. Additional properties are allowed.
Fields and variants
typestringRequired
Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired
namestring | nullRequired
tokensobjectRequired
The tokens the turn spent and the model they went to. Additional properties are allowed.
Fields and variants
cache_creationintegerRequired
Tokens written to the prompt cache.
cache_readintegerRequired
Tokens read from the prompt cache.
inputintegerRequired
Input tokens used.
modelstringRequired
The model the token counts are attributed to.
outputintegerRequired
Output tokens used.
totalintegerRequired
Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on.
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

1
{
2
"type": "records_append",
3
"records": [
4
{
5
"kind": "platform",
6
"source": "lifecycle",
7
"record_format": "ellipsis_lifecycle@1",
8
"record_type": "turn_started",
9
"id": "record_example",
10
"session_id": "session_example",
11
"turn_id": "turn_example",
12
"session_message_id": null,
13
"feed_seq": 12,
14
"payload": {
15
"turn_id": "turn_example",
16
"turn_index": 0
17
},
18
"tools": null,
19
"tokens_info": null,
20
"cost": null,
21
"duration": null,
22
"model": null,
23
"created_at": "2026-09-10T14:00:00Z"
24
}
25
]
26
}

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 the turn, the conversation, and cost.
Link to this event

Example JSON

1
{
2
"type": "session",
3
"session": {
4
"id": "session_example",
5
"conversation": {
6
"state": "open",
7
"interactive": true,
8
"warm": true,
9
"prompting": {
10
"enabled": true,
11
"blocked_reason": null,
12
"detail": null,
13
"surface_name": null
14
}
15
},
16
"turn": {
17
"id": "turn_example",
18
"index": 0,
19
"status": "running",
20
"reason": null,
21
"detail": null,
22
"stopped": null,
23
"created_at": "2026-09-10T14:00:00Z",
24
"started_at": "2026-09-10T14:00:09Z",
25
"ended_at": null,
26
"cost": {
27
"llm": 0,
28
"cpu": 0,
29
"memory": 0,
30
"fee": 0,
31
"total": 0
32
},
33
"tokens": {
34
"input": 0,
35
"output": 0,
36
"cache_read": 0,
37
"cache_creation": 0,
38
"total": 0,
39
"model": "claude-opus-5-5"
40
}
41
},
42
"archived": null,
43
"created_at": "2026-09-10T14:00:00Z",
44
"updated_at": "2026-09-10T14:00:12Z",
45
"source": "api",
46
"event": null,
47
"cost": {
48
"llm": 0,
49
"cpu": 0,
50
"memory": 0,
51
"fee": 0,
52
"total": 0
53
},
54
"tokens": {
55
"input": 0,
56
"output": 0,
57
"cache_read": 0,
58
"cache_creation": 0,
59
"total": 0,
60
"model": "claude-opus-5-5"
61
},
62
"parent": null,
63
"attribution": {
64
"type": "api_key",
65
"id": "key_example",
66
"user": null
67
},
68
"budget": 3.0,
69
"agent": null,
70
"handler": null,
71
"environment": {
72
"id": null,
73
"source": "platform_default",
74
"repositories": [],
75
"variables": [],
76
"compute": {
77
"cpu": null,
78
"memory": null,
79
"timeout": null
80
},
81
"hooks": {
82
"post_start": null,
83
"post_clone": null,
84
"build_base": null,
85
"after_checkout": null,
86
"before_start": null
87
},
88
"mcp_servers": []
89
},
90
"metadata": {},
91
"git": null,
92
"summary": {
93
"created_at": "2026-09-10T14:00:12Z",
94
"description": "Running the test suite."
95
},
96
"permissions": {
97
"ellipsis": true,
98
"github": {
99
"permissions": null,
100
"repositories": null
101
}
102
},
103
"skills": [],
104
"output": null,
105
"claude_code": {
106
"model": "claude-opus-5-5",
107
"effort": null,
108
"fallback_model": null,
109
"max_turns": null,
110
"settings": null,
111
"prompt": "Run the tests and report failures."
112
},
113
"codex": null
114
}
115
}

Field specification

typestringRequired
Must be "session".
sessionobjectRequired
The session's current state. Additional properties are not allowed.
Fields and variants
sourcestringRequired
Where the session came from (e.g. react, web, api, cli, mention, cron). Allowed values: "react", "code_review", "web", "api", "cli", "mention", "cron".
agentobject | nullRequired
The agent 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 agent definition the session was started from, frozen when the session was created. Additional properties are not allowed.
Fields and variants
ellipsisobjectRequired
Additional properties are not allowed.
Fields and variants
kindstringRequired
Must be "agent".
descriptionstring | nullRequired
enabledbooleanRequired
metadataobjectRequired
Additional properties are not allowed.
Fields and variants
annotationsobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
labelsarray<string>Required
Fields and variants
[]string
namestring | nullRequired
versionstringRequired
inputobject | nullRequired
Additional properties are not allowed.
Fields and variants
json_schemaobject | nullRequired
Additional properties are allowed.
messagestring | nullRequired
sessionobjectRequired
Additional properties are not allowed.
Fields and variants
budgetobjectRequired
Additional properties are not allowed.
Fields and variants
daynumber | nullRequired
The most the agent may spend over the last day, in US dollars.
monthnumber | nullRequired
The most the agent may spend over the last 28 days, in US dollars.
sessionnumber | nullRequired
The most one session may spend, in US dollars. Greater than: 0.
weeknumber | nullRequired
The most the agent may spend over the last 7 days, in US dollars.
claude_codeobject | nullRequired
Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Allowed values: "low", "medium", "high", "xhigh", "max".
fallback_modelstring | nullRequired
max_turnsinteger | nullRequired
Greater than: 0.
modelstringRequired
The model the session runs on: an alias or canonical id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
settingsobject | nullRequired
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
codexobject | nullRequired
Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringRequired
The model the session runs on: a Responses-capable id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
conversationobjectRequired
Additional properties are not allowed.
Fields and variants
interactivebooleanRequired
Whether the session stays open after its first turn. Defaults to true; false runs once and requires a prompt. Requires the model's interactive capability when true. Direct message acceptance is reported separately in conversation.prompting.
environmentstring | objectRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
computeobjectRequired
Additional properties are not allowed.
Fields and variants
cpuinteger | nullRequired
Minimum: 2. Maximum: 32.
memorystring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
gbinteger | nullRequired
Minimum: 0.
mbinteger | nullRequired
Minimum: 0.
timeoutstring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
hoursinteger | nullRequired
Minimum: 0.
minutesinteger | nullRequired
Minimum: 0.
secondsinteger | nullRequired
Minimum: 0.
hooksobjectRequired
Additional properties are not allowed.
Fields and variants
after_checkoutobject | string | nullRequired
Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared environment. Skipped when that prepared environment is reused. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
before_startobject | string | nullRequired
Run before the agent starts or resumes a session, after the environment is ready. This hook is not cached and adds to session startup time. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
build_baseobject | string | nullRequired
Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
inputsarray<string> | nullRequired
Exact files relative to the workspace directory `/sandbox`, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files.
Fields and variants
[]string
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
post_clonestring | nullRequired
Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation.
post_startstring | nullRequired
Legacy session startup script. Use before_start in new configurations.
mcp_serversarray<string | object>Required
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>Required
Fields and variants
[]string
commandstringRequired
envobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
variant 4object
Additional properties are not allowed.
Fields and variants
headersobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
urlstringRequired
repositoriesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
variablesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
valuestring | nullRequired
metadataobjectRequired
Arbitrary string key/value metadata stored on every session. Additional properties are allowed.
Fields and variants
[key]string
outputobject | nullRequired
Additional properties are not allowed.
Fields and variants
json_schemaobjectRequired
Additional properties are allowed.
permissionsobjectRequired
Additional properties are not allowed.
Fields and variants
ellipsisany JSON value | objectRequired
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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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> | nullRequired
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> | nullRequired
Fields and variants
[]string
githubobjectRequired
Additional properties are not allowed.
Fields and variants
permissionsstring | object | nullRequired
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> | nullRequired
Fields and variants
[]string
skillsarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
triggerobject | nullRequired
Matches exactly one variant below.
Fields and variants
type = "cron"object
Additional properties are not allowed.
Fields and variants
typestringRequired
Must be "cron".
schedulestringRequired
type = "react"object
Additional properties are not allowed.
Fields and variants
typestringRequired
Must be "react".
check_runobject | nullRequired
Additional properties are not allowed.
Fields and variants
brancharray<string>Required
Fields and variants
[]string
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
namesarray<string>Required
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "failed".
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
issueobject | nullRequired
Additional properties are not allowed.
Fields and variants
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
labelsarray<string>Required
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "opened", "closed", "commented".
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
linear_issueobject | nullRequired
Additional properties are not allowed.
Fields and variants
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "opened".
pull_requestobject | nullRequired
Additional properties are not allowed.
Fields and variants
basearray<string>Required
Fields and variants
[]string
draftboolean | nullRequired
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
headarray<string>Required
Fields and variants
[]string
labelsarray<string>Required
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented".
pathsarray<string>Required
Fields and variants
[]string
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
pushobject | nullRequired
Additional properties are not allowed.
Fields and variants
brancharray<string>Required
Fields and variants
[]string
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
pathsarray<string>Required
Fields and variants
[]string
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
releaseobject | nullRequired
Additional properties are not allowed.
Fields and variants
forobjectRequired
Additional properties are not allowed.
Fields and variants
botsobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
teamsarray<string>Required
Fields and variants
[]string
usersobject | boolean | array<string>Required
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>Required
Fields and variants
[]string
includearray<string> | booleanRequired
Matches at least one variant below.
Fields and variants
variant 1array<string>
Fields and variants
[]string
variant 2boolean
variant 2boolean
variant 3array<string>
Fields and variants
[]string
onarray<string>Required
Fields and variants
[]string
Allowed values: "published".
prereleaseboolean | nullRequired
repositoriesobject | array<string>Required
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>Required
Fields and variants
[]string
includearray<string>Required
Fields and variants
[]string
variant 2array<string>
Fields and variants
[]string
tagarray<string>Required
Fields and variants
[]string
sentryobject | nullRequired
Additional properties are not allowed.
Fields and variants
onarray<string>Required
Fields and variants
[]string
Allowed values: "issue_alert", "metric_alert".
projectsarray<string>Required
Fields and variants
[]string
slack_channelobject | nullRequired
Additional properties are not allowed.
idstring | nullRequired
Identifier of the saved agent this session's snapshot was taken from. Null for a routing-file agent or the built-in mention agent, which have no saved agent behind them. Points at the agent as it exists now, which may have changed since.
archivedobject | nullRequired
When and by whom the session was archived; null when unarchived. Archiving does not stop or close a session. Additional properties are allowed.
Fields and variants
atstringRequired
When the session was archived. Format: date-time.
byobject | nullRequired
The GitHub user who archived the session; null if unknown or unavailable. Additional properties are allowed.
Fields and variants
typestringRequired
Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired
namestring | nullRequired
attributionobjectRequired
The principal this session is attributed to. Additional properties are allowed.
Fields and variants
typestring | nullRequired
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 | nullRequired
Identifier of the principal the session is attributed to.
userobject | nullRequired
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
namestring | nullRequired
budgetnumberRequired
The spend budget enforced for this session, in US dollars, after resolving defaults and ceilings.
claude_codeobject | nullRequired
Claude Code input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Allowed values: "low", "medium", "high", "xhigh", "max".
fallback_modelstring | nullRequired
max_turnsinteger | nullRequired
Greater than: 0.
modelstringRequired
The model the session runs on: an alias or canonical id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
settingsobject | nullRequired
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
codexobject | nullRequired
Codex input and native options. Set exactly one of claude_code or codex. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Reasoning effort for every turn. Omit to use the model default. Allowed values: "none", "low", "medium", "high", "xhigh", "max".
modelstringRequired
The model the session runs on: a Responses-capable id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no turn, waiting for a message.
conversationobjectRequired
Whether the session can take more messages, and whether an agent is warm to answer one. Additional properties are allowed.
Fields and variants
interactivebooleanRequired
Whether the session stays open after its first turn.
promptingobjectRequired
The session's policy for direct messages. Caller authorization and message validation are checked separately. Additional properties are allowed.
Fields and variants
blocked_reasonstring | nullRequired
Allowed values: "mention_surface", "non_interactive", "harness_single_turn", "budget_exhausted", "closed".
detailstring | nullRequired
enabledbooleanRequired
surface_namestring | nullRequired
statestringRequired
`open` while the session can take messages; `closed` is permanent. Allowed values: "open", "closed".
warmbooleanRequired
Whether an agent is ready to answer the next message right away. When false, the next message first prepares an environment, which takes longer. A hint only; clients need no logic on it.
costobjectRequired
What the session has cost so far, in millicents, broken down by leg and carrying its own total. Additional properties are allowed.
Fields and variants
cpuintegerRequired
CPU spend in millicents.
feeintegerRequired
Platform fee in millicents.
llmintegerRequired
LLM spend in millicents.
memoryintegerRequired
Memory spend in millicents.
totalintegerRequired
The grand total in millicents: llm + cpu + memory + fee.
created_atstringRequired
When the session was created. Format: date-time.
environmentobjectRequired
The full environment configuration frozen when the session was created, with the saved environment's id and how it was chosen. Additional properties are not allowed.
Fields and variants
sourcestring | nullRequired
How the environment was chosen (request, agent, platform_default; repo_default and account_default on sessions from before those ladders were removed). An inline request uses request; an inline environment declared in session configuration has no source. Allowed values: "request", "agent", "repo_default", "account_default", "platform_default".
computeobjectRequired
Additional properties are not allowed.
Fields and variants
cpuinteger | nullRequired
Minimum: 2. Maximum: 32.
memorystring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
gbinteger | nullRequired
Minimum: 0.
mbinteger | nullRequired
Minimum: 0.
timeoutstring | object | nullRequired
Matches at least one variant below.
Fields and variants
variant 1string
variant 2object
Additional properties are not allowed.
Fields and variants
hoursinteger | nullRequired
Minimum: 0.
minutesinteger | nullRequired
Minimum: 0.
secondsinteger | nullRequired
Minimum: 0.
hooksobjectRequired
Additional properties are not allowed.
Fields and variants
after_checkoutobject | string | nullRequired
Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared environment. Skipped when that prepared environment is reused. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
before_startobject | string | nullRequired
Run before the agent starts or resumes a session, after the environment is ready. This hook is not cached and adds to session startup time. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
build_baseobject | string | nullRequired
Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs. Matches at least one variant below.
Fields and variants
variant 1object
Additional properties are not allowed.
Fields and variants
inputsarray<string> | nullRequired
Exact files relative to the workspace directory `/sandbox`, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files.
Fields and variants
[]string
runstringRequired
Shell script to run in the workspace directory `/sandbox`.
variant 2string
post_clonestring | nullRequired
Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation.
post_startstring | nullRequired
Legacy session startup script. Use before_start in new configurations.
idstring | nullRequired
Identifier of the saved environment the session's config resolved. Null for an inline environment block or the built-in basic environment.
mcp_serversarray<string | object>Required
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>Required
Fields and variants
[]string
commandstringRequired
envobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
variant 4object
Additional properties are not allowed.
Fields and variants
headersobjectRequired
Additional properties are allowed.
Fields and variants
[key]string
namestringRequired
urlstringRequired
repositoriesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
variablesarray<object>Required
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
namestringRequired
valuestring | nullRequired
eventobject | nullRequired
The typed external event that started the session; null for direct and scheduled starts. Matches exactly one variant below.
Fields and variants
type = "github.pull_request"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.pull_request".
actionstringRequired
Matches at least one variant below.
Fields and variants
variant 1string
Allowed values: "opened", "pushed", "merged", "closed", "review_submitted", "commented".
variant 2string
Must be "review_commented".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
branchstringRequired
numberintegerRequired
repositorystringRequired
titlestringRequired
urlstringRequired
type = "github.issue"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.issue".
actionstringRequired
Allowed values: "opened", "closed", "commented".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
numberintegerRequired
repositorystringRequired
titlestringRequired
urlstringRequired
type = "github.push"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.push".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
afterstringRequired
beforestringRequired
branchstringRequired
repositorystringRequired
urlstringRequired
type = "github.check_run"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.check_run".
actionstringRequired
Allowed values: "failed".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
branchstring | nullRequired
conclusionstring | nullRequired
head_shastringRequired
namestringRequired
pull_request_numberinteger | nullRequired
repositorystringRequired
urlstringRequired
type = "github.release"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.release".
actionstringRequired
Allowed values: "published".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
namestring | nullRequired
prereleasebooleanRequired
repositorystringRequired
tagstringRequired
urlstringRequired
type = "linear.issue"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "linear.issue".
actionstringRequired
Matches at least one variant below.
Fields and variants
variant 1string
Allowed values: "opened".
variant 2string
Must be "commented".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
identifierstring | nullRequired
numberintegerRequired
titlestringRequired
urlstringRequired
type = "slack.message"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "slack.message".
actionstringRequired
Allowed values: "message", "app_mention".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
channel_idstringRequired
channel_namestring | nullRequired
message_tsstringRequired
thread_tsstring | nullRequired
urlstringRequired
type = "slack.channel_created"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "slack.channel_created".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
channel_idstringRequired
channel_namestring | nullRequired
urlstringRequired
type = "sentry.alert"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "sentry.alert".
actionstringRequired
Allowed values: "issue_alert", "metric_alert".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
organization_slugstringRequired
project_slugstring | nullRequired
titlestring | nullRequired
urlstring | nullRequired
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>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
commitsarray<object>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
committed_atstringRequired
Format: date-time.
pushedbooleanRequired
shastringRequired
subjectstringRequired
commits_totalintegerRequired
full_namestringRequired
local_commitstring | nullRequired
local_uncommitted_filesarray<object>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
additionsintegerRequired
deletionsintegerRequired
pathstringRequired
statusstringRequired
prsarray<object>Required
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
gh_pr_idinteger | nullRequired
numberintegerRequired
titlestring | nullRequired
urlstringRequired
remote_branchstring | nullRequired
remote_commitstring | nullRequired
handlerobject | nullRequired
The saved handler and its effective display name when this session started, frozen at creation. Null for built-in responders, legacy sessions, and sessions started without a handler. Additional properties are allowed.
Fields and variants
agent_namestringRequired
The handler's effective display name when the session started: ellipsis.name, or the service default (Slack, GitHub, Linear, or sentry).
idstringRequired
Identifier of the saved handler.
servicestringRequired
The service the handler responds to. Allowed values: "slack", "github", "linear", "sentry".
shastringRequired
Content fingerprint of the validated handler configuration used when the session started. This is not the Git commit SHA.
idstringRequired
Unique identifier of the session.
metadataobjectRequired
Caller-supplied metadata key-value pairs. Additional properties are allowed.
Fields and variants
[key]string
outputobject | nullRequired
The structured-output exit contract for this session. Additional properties are not allowed.
Fields and variants
json_schemaobjectRequired
Additional properties are allowed.
parentobject | nullRequired
The predecessor session this session continues; null when there is none. Additional properties are allowed.
Fields and variants
session_idstring | nullRequired
Identifier of the predecessor session this session continues, if any.
permissionsobjectRequired
What the session may touch, per minted credential. Additional properties are not allowed.
Fields and variants
ellipsisany JSON value | objectRequired
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", "configs", "defaults", "environments", "secrets", "templates", "integrations", "reviews", "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> | nullRequired
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> | nullRequired
Fields and variants
[]string
githubobjectRequired
Additional properties are not allowed.
Fields and variants
permissionsstring | object | nullRequired
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> | nullRequired
Fields and variants
[]string
skillsarray<object>Required
Skills installed for this session.
Fields and variants
[]object
Additional properties are not allowed.
Fields and variants
pathstringRequired
repositoryobject | nullRequired
Additional properties are not allowed.
Fields and variants
namestringRequired
ownerstring | nullRequired
refstring | nullRequired
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 | nullRequired
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 doing.
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_creationintegerRequired
Tokens written to the prompt cache.
cache_readintegerRequired
Tokens read from the prompt cache.
inputintegerRequired
Input tokens used.
modelstringRequired
The model the token counts are attributed to.
outputintegerRequired
Output tokens used.
totalintegerRequired
Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on.
turnobject | nullRequired
The turn in progress, or the latest one when none is running. Null until the session has a message. Wait on it: the message you sent is answered when the turn with your message's `turn_id` reaches a final status. Additional properties are allowed.
Fields and variants
costobjectRequired
What the turn cost so far, in millicents, broken down by leg. Additional properties are allowed.
Fields and variants
cpuintegerRequired
CPU spend in millicents.
feeintegerRequired
Platform fee in millicents.
llmintegerRequired
LLM spend in millicents.
memoryintegerRequired
Memory spend in millicents.
totalintegerRequired
The grand total in millicents: llm + cpu + memory + fee.
created_atstringRequired
When the turn's message was received. Format: date-time.
detailstring | nullRequired
A human-readable explanation of a failed, stopped, or cancelled turn.
ended_atstring | nullRequired
When the turn reached its final status. Format: date-time.
idstringRequired
Unique identifier of the turn.
indexintegerRequired
Position in the session, starting at 0.
reasonstring | nullRequired
Why the turn failed or was cancelled; null on every other status. Allowed values: "error", "tool_call_failed", "budget_hit", "payment_required", "blocked", "contact_email_required", "lifecycle_hook_failed", "missing_repo_access", "missing_token_permissions", "missing_environment_variables", "missing_github_integration", "agent_unavailable", "upstream_unavailable", "unsupported_configuration", "execution_disabled", "interrupted".
started_atstring | nullRequired
When the agent started on the message. Format: date-time.
statusstringRequired
Where the turn is. Allowed values: "pending", "running", "completed", "failed", "stopped", "cancelled".
stoppedobject | nullRequired
When and by whom a stop was requested; null when none was. Additional properties are allowed.
Fields and variants
atstringRequired
When a stop was requested. Format: date-time.
byobject | nullRequired
The GitHub user who stopped the session, resolved at read time. Null if the user is unknown or unavailable. Additional properties are allowed.
Fields and variants
typestringRequired
Allowed values: "User", "Organization", "Bot", "Mannequin".
avatar_urlstringRequired
idintegerRequired
loginstringRequired
namestring | nullRequired
tokensobjectRequired
The tokens the turn spent and the model they went to. Additional properties are allowed.
Fields and variants
cache_creationintegerRequired
Tokens written to the prompt cache.
cache_readintegerRequired
Tokens read from the prompt cache.
inputintegerRequired
Input tokens used.
modelstringRequired
The model the token counts are attributed to.
outputintegerRequired
Output tokens used.
totalintegerRequired
Total tokens consumed, INCLUDING the prompt-cache reads and writes — the same basis the token cost is priced on.
updated_atstringRequired
When the session was last updated. Format: date-time.
deltaStreams assistant text, a live reasoning-summary preview, or a response output-token count.
Link to this event

Example JSON

1
{
2
"type": "delta",
3
"turn_id": "turn_example",
4
"kind": "text",
5
"text": "All 12 tests",
6
"output_tokens": 4
7
}

Field specification

typestringRequired
Must be "delta".
kindstringRequired
Known values: text (append assistant output), thinking (replace the readable reasoning-summary preview). Open vocabulary: ignore deltas with unknown kinds.
output_tokensinteger | nullRequired
Output tokens generated so far for the current response.
textstring | nullRequired
For "text", an append-only fragment. For "thinking", the first-line prefix of the latest summary section (at most 512 characters); replace the preview, and clear it on an empty string. Null means no text update.
turn_idstring | nullRequired
Identifier of the turn the delta belongs to, if known.
deltaReplaces the current readable reasoning-summary preview while the agent works (kind: thinking).
Link to this event

For a working subtitle, replace your current preview with each thinking update. This illustrative update contains a summary heading:

1
{
2
"type": "delta",
3
"turn_id": "turn_example",
4
"kind": "thinking",
5
"text": "**Inspecting the mock server**",
6
"output_tokens": null
7
}

Field specification

typestringRequired
Must be "delta".
kindstringRequired
Known values: text (append assistant output), thinking (replace the readable reasoning-summary preview). Open vocabulary: ignore deltas with unknown kinds.
output_tokensinteger | nullRequired
Output tokens generated so far for the current response.
textstring | nullRequired
For "text", an append-only fragment. For "thinking", the first-line prefix of the latest summary section (at most 512 characters); replace the preview, and clear it on an empty string. Null means no text update.
turn_idstring | nullRequired
Identifier of the turn the delta belongs to, if known.
heartbeatKeeps a quiet connection alive, normally after 20 seconds without other updates.
Link to this event

Example JSON

1
{
2
"type": "heartbeat",
3
"ts": "2026-09-10T14:00:00Z"
4
}

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

1
{
2
"type": "done"
3
}

Field specification

typestringRequired
Must be "done".
errorReports a stream-server failure before the socket closes.
Link to this event

Example JSON

1
{
2
"type": "error",
3
"message": "Something went wrong streaming this session."
4
}

Field specification

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

For delta.kind: "text", append text to the live assistant response. For kind: "thinking", replace the summary preview with text; it contains at most 512 characters from the first line of the current readable summary section. An empty string clears the preview, and null leaves it unchanged. Thinking previews do not change the output-token counter. Clear the preview when the agent starts writing, the turn ends, or a reconnect supplies a new snapshot. Models that do not emit readable summaries keep the generic working indicator.

A text 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. Ignore unknown delta kinds.

An open conversation stays connected between turns without a done frame; done follows closure, not the end of each turn. The message you sent is answered when a session frame shows the turn with its turn_id at a final status; see Lifecycle.

Historical formats

Existing history keeps its original payload format. These examples cover compatibility when reading or replaying older sessions; new sessions 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

1
{
2
"kind": "claude_sdk",
3
"source": "claude_code",
4
"record_format": "claude_sdk@1",
5
"record_type": "system",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"kind": "system",
13
"subtype": "init",
14
"data": {
15
"model": "claude-opus-5-5"
16
},
17
"session_id": "11111111-1111-4111-8111-111111111111"
18
},
19
"tools": null,
20
"tokens_info": null,
21
"cost": null,
22
"duration": null,
23
"model": null,
24
"created_at": "2026-09-10T14:00:00Z"
25
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
userCarries a historical user prompt or tool-result content.
Link to this event

Example JSON

1
{
2
"kind": "claude_sdk",
3
"source": "claude_code",
4
"record_format": "claude_sdk@1",
5
"record_type": "user",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"kind": "user",
13
"content": "Run the tests and report failures."
14
},
15
"tools": null,
16
"tokens_info": null,
17
"cost": null,
18
"duration": null,
19
"model": null,
20
"created_at": "2026-09-10T14:00:00Z"
21
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
assistantCarries historical assistant content with its model at the payload root.
Link to this event

Example JSON

1
{
2
"kind": "claude_sdk",
3
"source": "claude_code",
4
"record_format": "claude_sdk@1",
5
"record_type": "assistant",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"kind": "assistant",
13
"model": "claude-opus-5-5",
14
"content": [
15
{
16
"type": "text",
17
"text": "All 12 tests passed."
18
}
19
]
20
},
21
"tools": null,
22
"tokens_info": null,
23
"cost": null,
24
"duration": null,
25
"model": "claude-opus-5-5",
26
"created_at": "2026-09-10T14:00:00Z"
27
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
resultReports a historical turn outcome with cost_usd rather than the native total_cost_usd field.
Link to this event

Example JSON

1
{
2
"kind": "claude_sdk",
3
"source": "claude_code",
4
"record_format": "claude_sdk@1",
5
"record_type": "result",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"kind": "result",
13
"subtype": "success",
14
"is_error": false,
15
"num_turns": 1,
16
"duration_ms": 4200,
17
"duration_api_ms": 3100,
18
"result": "All 12 tests passed.",
19
"cost_usd": 0.01
20
},
21
"tools": null,
22
"tokens_info": null,
23
"cost": 1000,
24
"duration": 4200,
25
"model": null,
26
"created_at": "2026-09-10T14:00:00Z"
27
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
rate_limitReports historical rate-limit information with snake_case fields.
Link to this event

Example JSON

1
{
2
"kind": "claude_sdk",
3
"source": "claude_code",
4
"record_format": "claude_sdk@1",
5
"record_type": "rate_limit",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"kind": "rate_limit",
13
"status": "allowed",
14
"rate_limit_type": "five_hour",
15
"utilization": 0.25,
16
"resets_at": 1789066800
17
},
18
"tools": null,
19
"tokens_info": null,
20
"cost": null,
21
"duration": null,
22
"model": null,
23
"created_at": "2026-09-10T14:00:00Z"
24
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.

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

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "thread.started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "thread.started",
13
"thread_id": "thread_example"
14
},
15
"tools": null,
16
"tokens_info": null,
17
"cost": null,
18
"duration": null,
19
"model": null,
20
"created_at": "2026-09-10T14:00:00Z"
21
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn.startedAnnounces a historical native turn beginning.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "turn.started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "turn.started"
13
},
14
"tools": null,
15
"tokens_info": null,
16
"cost": null,
17
"duration": null,
18
"model": null,
19
"created_at": "2026-09-10T14:00:00Z"
20
}

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".
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
item.startedAnnounces a historical conversation item beginning.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "item.started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "item.started",
13
"item": {
14
"id": "command_example",
15
"type": "command_execution",
16
"command": "pytest -q",
17
"status": "in_progress",
18
"aggregated_output": ""
19
}
20
},
21
"tools": [
22
"Bash"
23
],
24
"tokens_info": null,
25
"cost": null,
26
"duration": null,
27
"model": null,
28
"created_at": "2026-09-10T14:00:00Z"
29
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
item.updatedSupplies an update to an existing historical item.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "item.updated",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "item.updated",
13
"item": {
14
"id": "command_example",
15
"type": "command_execution",
16
"command": "pytest -q",
17
"status": "in_progress",
18
"aggregated_output": "Running 12 tests..."
19
}
20
},
21
"tools": [
22
"Bash"
23
],
24
"tokens_info": null,
25
"cost": null,
26
"duration": null,
27
"model": null,
28
"created_at": "2026-09-10T14:00:00Z"
29
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
item.completedSupplies a historical item's completed content or outcome.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "item.completed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "item.completed",
13
"item": {
14
"id": "command_example",
15
"type": "command_execution",
16
"command": "pytest -q",
17
"status": "completed",
18
"aggregated_output": "12 passed",
19
"exit_code": 0
20
}
21
},
22
"tools": [
23
"Bash"
24
],
25
"tokens_info": null,
26
"cost": null,
27
"duration": null,
28
"model": null,
29
"created_at": "2026-09-10T14:00:00Z"
30
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn.completedReports successful historical turn completion and usage.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "turn.completed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "turn.completed",
13
"usage": {
14
"input_tokens": 1200,
15
"output_tokens": 80,
16
"cached_input_tokens": 0
17
}
18
},
19
"tools": null,
20
"tokens_info": {
21
"input_tokens": 1200,
22
"output_tokens": 80,
23
"cache_read_input_tokens": 0,
24
"cache_creation_input_tokens": 0,
25
"num_turns": 0,
26
"cost_usd": 0
27
},
28
"cost": null,
29
"duration": null,
30
"model": null,
31
"created_at": "2026-09-10T14:00:00Z"
32
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
turn.failedReports a failed historical turn with its error.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "turn.failed",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "turn.failed",
13
"error": {
14
"message": "The model request timed out."
15
}
16
},
17
"tools": null,
18
"tokens_info": null,
19
"cost": null,
20
"duration": null,
21
"model": null,
22
"created_at": "2026-09-10T14:00:00Z"
23
}

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.
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.
errorReports a historical native error.
Link to this event

Example JSON

1
{
2
"kind": "codex",
3
"source": "codex",
4
"record_format": "codex_jsonl@1",
5
"record_type": "error",
6
"id": "record_example",
7
"session_id": "session_example",
8
"turn_id": "turn_example",
9
"session_message_id": null,
10
"feed_seq": 12,
11
"payload": {
12
"type": "error",
13
"message": "The model request timed out."
14
},
15
"tools": null,
16
"tokens_info": null,
17
"cost": null,
18
"duration": null,
19
"model": null,
20
"created_at": "2026-09-10T14:00:00Z"
21
}

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
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
session_idstringRequired
Session containing this record.
session_message_idstring | nullRequired
Message this record receives, delivers, requeues, or echoes.
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_idstring | nullRequired
Turn containing this record, when applicable.

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, payloads that the current typed schema cannot interpret, and platform record types from older sessions that are no longer produced. 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

Read an eventPlatformClaude CodeCodexWebSocket framesHistorical formatsClaude SDK recordsCodex JSONL recordsUnknown records
Schedule a demo