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 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 its end.

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 a session reports 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, one of platform, claude_code, codex_app_server, gemini, claude_sdk, codex, or unknown.
sourceIdentify the producer, one of lifecycle, claude_code, codex, or gemini.
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.
message_idCorrelate records with the message they belong to. Environment records carry the message they prepare for.

Use kind and record_type to narrow platform records. For native records, narrow kind first, then payload.type (Claude, Gemini CLI, 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 message carries its message_id. Environment records carry the message they prepare for. Older sessions can contain platform record types that are no longer produced. They arrive as unknown records.

messageA message was sent to the session. The payload is the same object POST /v1/sessions/{id}/messages returns.
Link to this event

Match a native user echo to this record by message_id so the message renders once. The message is answered when its message_ended record arrives. See Lifecycle.

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "message",
6
"id": "record_example",
7
"session_id": "session_example",
8
"message_id": "message_example",
9
"feed_seq": 1,
10
"payload": {
11
"id": "message_example",
12
"session_id": "session_example",
13
"index": 0,
14
"body": "Run the tests and report failures.",
15
"images": [],
16
"author": "priya-shah",
17
"created_at": "2026-09-10T14:00:00Z"
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 "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "message".
payloadobjectRequired
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 received. Format: date-time.
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.
indexintegerRequired
Position in the session, starting at 0.
session_idstringRequired
Identifier of the session the message belongs to.
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
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
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
"message_id": "message_example",
9
"feed_seq": 2,
10
"payload": {
11
"phase": "setup",
12
"status": "completed",
13
"step": "after_checkout",
14
"duration_ms": 2400,
15
"detail": null
16
},
17
"tools": null,
18
"tokens_info": null,
19
"cost": null,
20
"duration": null,
21
"model": null,
22
"created_at": "2026-09-10T14:00:03Z"
23
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
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
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
"message_id": "message_example",
9
"feed_seq": 3,
10
"payload": {
11
"phase": "clone",
12
"step": "your-org/api-repo",
13
"stream": "stdout",
14
"chunk": 0,
15
"lines": [
16
"Cloning into 'api-repo'..."
17
]
18
},
19
"tools": null,
20
"tokens_info": null,
21
"cost": null,
22
"duration": null,
23
"model": null,
24
"created_at": "2026-09-10T14:00:01Z"
25
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
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
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
"message_id": "message_example",
9
"feed_seq": 4,
10
"payload": {
11
"repositories": [
12
"your-org/api-repo"
13
],
14
"duration_ms": 8400
15
},
16
"tools": null,
17
"tokens_info": null,
18
"cost": null,
19
"duration": null,
20
"model": null,
21
"created_at": "2026-09-10T14:00:08Z"
22
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
message_queuedThe message waits because the account already has its limit of sessions alive.
Link to this event

Example JSON

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

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "message_queued".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
limitintegerRequired
message_idstringRequired
sessions_aliveintegerRequired
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
message_startedThe agent started on the message and the session 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": "message_started",
6
"id": "record_example",
7
"session_id": "session_example",
8
"message_id": "message_example",
9
"feed_seq": 5,
10
"payload": {
11
"message_id": "message_example"
12
},
13
"tools": null,
14
"tokens_info": null,
15
"cost": null,
16
"duration": null,
17
"model": null,
18
"created_at": "2026-09-10T14:00:09Z"
19
}

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "message_started".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
message_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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
message_endedThe message was answered, or its answer failed, was stopped, or was cancelled. error is the same object as the session's error, null when the message was answered. cost and tokens are what answering it spent, reported once on the last of the messages answered together.
Link to this event

Example JSON

1
{
2
"kind": "platform",
3
"source": "lifecycle",
4
"record_format": "ellipsis_lifecycle@1",
5
"record_type": "message_ended",
6
"id": "record_example",
7
"session_id": "session_example",
8
"message_id": "message_example",
9
"feed_seq": 7,
10
"payload": {
11
"message_id": "message_example",
12
"status": "completed",
13
"error": null,
14
"duration_ms": 4200,
15
"cost": {
16
"llm": {
17
"all": {
18
"platform": 1520,
19
"claude_subscription": 0,
20
"codex_subscription": 0,
21
"total": 1520
22
},
23
"by_model": []
24
},
25
"cpu": 40,
26
"memory": 0,
27
"fee": 0,
28
"charged": 1560,
29
"total": 1560
30
},
31
"tokens": {
32
"all": {
33
"input": 12,
34
"output": 85,
35
"cache_read": 20100,
36
"cache_creation": 900,
37
"total": 21097
38
},
39
"by_model": []
40
}
41
},
42
"tools": null,
43
"tokens_info": null,
44
"cost": null,
45
"duration": null,
46
"model": null,
47
"created_at": "2026-09-10T14:00:13Z"
48
}

Field specification

kindstringRequired
Must be "platform".
sourcestringRequired
Must be "lifecycle".
record_formatstringRequired
Must be "ellipsis_lifecycle@1".
record_typestringRequired
Must be "message_ended".
payloadobjectRequired
Additional properties are allowed.
Fields and variants
costobjectOptional
Additional properties are allowed.
Fields and variants
chargedintegerRequired
What Ellipsis charged to credit, in millicents. It is everything except subscription tokens.
cpuintegerRequired
CPU spend in millicents.
feeintegerRequired
Platform fee in millicents.
llmobjectRequired
LLM token cost, in total and by model, split by who paid. Additional properties are allowed.
Fields and variants
allobjectRequired
Token cost across every model. Additional properties are allowed.
Fields and variants
claude_subscriptionintegerRequired
Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
codex_subscriptionintegerRequired
Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
platformintegerRequired
Token cost charged to Ellipsis credit, in millicents.
totalintegerRequired
All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
by_modelarray<object>Required
Token cost for each model that used tokens.
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
claude_subscriptionintegerRequired
Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
codex_subscriptionintegerRequired
Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
modelstringRequired
The model that used these tokens.
platformintegerRequired
Token cost charged to Ellipsis credit, in millicents.
totalintegerRequired
All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
memoryintegerRequired
Memory spend in millicents.
totalintegerRequired
Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps.
duration_msinteger | nullOptional
errorobject | nullOptional
Additional properties are allowed.
Fields and variants
detailstring | nullRequired
A human-readable explanation.
reasonstringRequired
What went wrong. 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", "stopped".
message_idstringRequired
statusstringRequired
tokensobjectOptional
Additional properties are allowed.
Fields and variants
allobjectRequired
Token counts across every model. 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.
outputintegerRequired
Output tokens used.
totalintegerRequired
All tokens used, including prompt cache reads and writes. Token cost is priced on this.
by_modelarray<object>Required
Token counts for each model that used tokens.
Fields and variants
[]object
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 that used these tokens.
outputintegerRequired
Output tokens used.
totalintegerRequired
All tokens used, including prompt cache reads and writes. Token cost is priced on this.
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
message_requeuedThe agent was interrupted before answering, so the message goes back to the inbox and starts again on a fresh environment.
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
"message_id": "message_example",
9
"feed_seq": 8,
10
"payload": {
11
"message_id": "message_example"
12
},
13
"tools": null,
14
"tokens_info": null,
15
"cost": null,
16
"duration": null,
17
"model": null,
18
"created_at": "2026-09-10T14:00:13Z"
19
}

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
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
session_closedThe session closed permanently, after the first message of a session that runs once or after a closing message.
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
"message_id": null,
9
"feed_seq": 10,
10
"payload": {},
11
"tools": null,
12
"tokens_info": null,
13
"cost": null,
14
"duration": null,
15
"model": null,
16
"created_at": "2026-09-10T14:00:14Z"
17
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
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

environment_phase.phase names a stage of preparation, one of 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 message), 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.

How a message ended also reaches the session frame as status and error. message_ended is the record of the same change. There are no separate session-level success, failure, or stop records. The session 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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "system",
12
"subtype": "init",
13
"model": "claude-opus-5-5",
14
"tools": [
15
"Bash",
16
"Read"
17
],
18
"cwd": "/workspace",
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
systemReports a Git state change through subtype: vcs_state_changed; payload.kind identifies the operation, such as a push.
Link to this event

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

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "system",
12
"subtype": "vcs_state_changed",
13
"kind": "push",
14
"cwd": "/workspace",
15
"session_id": "11111111-1111-4111-8111-111111111111",
16
"uuid": "22222222-2222-4222-8222-222222222222"
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_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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
userCarries a user-message echo or tool results supplied back to Claude; this example is a tool result.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "user",
12
"message": {
13
"role": "user",
14
"content": [
15
{
16
"type": "tool_result",
17
"tool_use_id": "tool_example",
18
"content": "12 passed",
19
"is_error": false
20
}
21
]
22
},
23
"parent_tool_use_id": null,
24
"session_id": "11111111-1111-4111-8111-111111111111",
25
"uuid": "22222222-2222-4222-8222-222222222222"
26
},
27
"tools": null,
28
"tokens_info": null,
29
"cost": null,
30
"duration": null,
31
"model": null,
32
"created_at": "2026-09-10T14:00:00Z"
33
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
assistantCarries completed assistant content, including text, thinking, and tool calls.
Link to this event

Example JSON

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

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
rate_limitReports rate-limit status and reset information; the native payload names the event rate_limit_event.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "rate_limit_event",
12
"rate_limit_info": {
13
"status": "allowed",
14
"rateLimitType": "five_hour",
15
"utilization": 0.25,
16
"resetsAt": 1789066800
17
},
18
"session_id": "11111111-1111-4111-8111-111111111111",
19
"uuid": "22222222-2222-4222-8222-222222222222"
20
},
21
"tools": null,
22
"tokens_info": null,
23
"cost": null,
24
"duration": null,
25
"model": null,
26
"created_at": "2026-09-10T14:00:00Z"
27
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
resultReports a harness turn outcome with its output, elapsed time, usage, and reported cost.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "result",
12
"subtype": "success",
13
"is_error": false,
14
"num_turns": 1,
15
"duration_ms": 4200,
16
"duration_api_ms": 3100,
17
"result": "All 12 tests passed.",
18
"total_cost_usd": 0.01,
19
"usage": {
20
"input_tokens": 1200,
21
"output_tokens": 80,
22
"cache_read_input_tokens": 0,
23
"cache_creation_input_tokens": 0
24
},
25
"session_id": "11111111-1111-4111-8111-111111111111",
26
"uuid": "22222222-2222-4222-8222-222222222222"
27
},
28
"tools": null,
29
"tokens_info": {
30
"input_tokens": 1200,
31
"output_tokens": 80,
32
"cache_read_input_tokens": 0,
33
"cache_creation_input_tokens": 0,
34
"num_turns": 0,
35
"cost_usd": 0
36
},
37
"cost": 1000,
38
"duration": 4200,
39
"model": null,
40
"created_at": "2026-09-10T14:00:00Z"
41
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
conversation_resetReports that Claude switched to a new native conversation identifier.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "conversation_reset",
12
"new_conversation_id": "33333333-3333-4333-8333-333333333333",
13
"session_id": "11111111-1111-4111-8111-111111111111",
14
"uuid": "22222222-2222-4222-8222-222222222222"
15
},
16
"tools": null,
17
"tokens_info": null,
18
"cost": null,
19
"duration": null,
20
"model": null,
21
"created_at": "2026-09-10T14:00:00Z"
22
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string

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

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

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

Codex

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

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

Example JSON

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
"message_id": null,
9
"feed_seq": 12,
10
"payload": {
11
"method": "remoteControl/status/changed",
12
"params": {
13
"status": "disabled",
14
"serverName": "sandbox",
15
"installationId": "installation_example",
16
"environmentId": null
17
}
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
thread/startedAnnounces the native thread and its metadata.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "thread/started",
12
"params": {
13
"thread": {
14
"id": "thread_example",
15
"cliVersion": "0.161.0",
16
"modelProvider": "openai",
17
"cwd": "/workspace/api-repo",
18
"turns": []
19
}
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
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
type = "subAgentActivity"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "subAgentActivity".
kindstringRequired
agentPathstring | nullOptional
agentThreadIdstringRequired
idstringRequired
type = "collabAgentToolCall"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "collabAgentToolCall".
idstringRequired
promptstring | nullOptional
receiverThreadIdsarray<string>Required
Fields and variants
[]string
senderThreadIdstringRequired
statusstringRequired
Allowed values: "inProgress", "completed", "failed".
toolstringRequired
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
thread/status/changedReports native thread activity, such as becoming active or idle, as an unknown record.
Link to this event

Example JSON

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
"message_id": null,
9
"feed_seq": 12,
10
"payload": {
11
"method": "thread/status/changed",
12
"params": {
13
"threadId": "thread_example",
14
"status": {
15
"type": "idle"
16
}
17
}
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
turn/startedAnnounces the start of a native turn.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "turn/started",
12
"params": {
13
"threadId": "thread_example",
14
"turn": {
15
"id": "native_turn_example",
16
"status": "inProgress",
17
"items": [],
18
"error": null
19
}
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
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
type = "subAgentActivity"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "subAgentActivity".
kindstringRequired
agentPathstring | nullOptional
agentThreadIdstringRequired
idstringRequired
type = "collabAgentToolCall"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "collabAgentToolCall".
idstringRequired
promptstring | nullOptional
receiverThreadIdsarray<string>Required
Fields and variants
[]string
senderThreadIdstringRequired
statusstringRequired
Allowed values: "inProgress", "completed", "failed".
toolstringRequired
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
item/startedAnnounces the start of a message, command, file change, or another conversation item.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "item/started",
12
"params": {
13
"threadId": "thread_example",
14
"turnId": "native_turn_example",
15
"item": {
16
"type": "commandExecution",
17
"id": "command_example",
18
"command": "pytest -q",
19
"cwd": "/workspace/api-repo",
20
"commandActions": [],
21
"status": "inProgress"
22
}
23
}
24
},
25
"tools": [
26
"Bash"
27
],
28
"tokens_info": null,
29
"cost": null,
30
"duration": null,
31
"model": null,
32
"created_at": "2026-09-10T14:00:00Z"
33
}

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
type = "subAgentActivity"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "subAgentActivity".
kindstringRequired
agentPathstring | nullOptional
agentThreadIdstringRequired
idstringRequired
type = "collabAgentToolCall"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "collabAgentToolCall".
idstringRequired
promptstring | nullOptional
receiverThreadIdsarray<string>Required
Fields and variants
[]string
senderThreadIdstringRequired
statusstringRequired
Allowed values: "inProgress", "completed", "failed".
toolstringRequired
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
item/completedSupplies a completed item, including its content, output, or outcome.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "item/completed",
12
"params": {
13
"threadId": "thread_example",
14
"turnId": "native_turn_example",
15
"item": {
16
"type": "commandExecution",
17
"id": "command_example",
18
"command": "pytest -q",
19
"cwd": "/workspace/api-repo",
20
"commandActions": [],
21
"status": "completed",
22
"aggregatedOutput": "12 passed",
23
"exitCode": 0,
24
"durationMs": 4200
25
}
26
}
27
},
28
"tools": [
29
"Bash"
30
],
31
"tokens_info": null,
32
"cost": null,
33
"duration": null,
34
"model": null,
35
"created_at": "2026-09-10T14:00:00Z"
36
}

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
type = "subAgentActivity"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "subAgentActivity".
kindstringRequired
agentPathstring | nullOptional
agentThreadIdstringRequired
idstringRequired
type = "collabAgentToolCall"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "collabAgentToolCall".
idstringRequired
promptstring | nullOptional
receiverThreadIdsarray<string>Required
Fields and variants
[]string
senderThreadIdstringRequired
statusstringRequired
Allowed values: "inProgress", "completed", "failed".
toolstringRequired
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
thread/tokenUsage/updatedReports cumulative native thread usage and usage for the latest model call.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "thread/tokenUsage/updated",
12
"params": {
13
"threadId": "thread_example",
14
"turnId": "native_turn_example",
15
"tokenUsage": {
16
"total": {
17
"inputTokens": 1200,
18
"outputTokens": 80,
19
"cachedInputTokens": 0,
20
"reasoningOutputTokens": 0,
21
"totalTokens": 1280
22
},
23
"last": {
24
"inputTokens": 1200,
25
"outputTokens": 80,
26
"cachedInputTokens": 0,
27
"reasoningOutputTokens": 0,
28
"totalTokens": 1280
29
},
30
"modelContextWindow": 272000
31
}
32
}
33
},
34
"tools": null,
35
"tokens_info": {
36
"input_tokens": 1200,
37
"output_tokens": 80,
38
"cache_read_input_tokens": 0,
39
"cache_creation_input_tokens": 0,
40
"num_turns": 0,
41
"cost_usd": 0
42
},
43
"cost": null,
44
"duration": null,
45
"model": null,
46
"created_at": "2026-09-10T14:00:00Z"
47
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
account/rateLimits/updatedReports native account rate-limit information as an unknown record.
Link to this event

Example JSON

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
"message_id": null,
9
"feed_seq": 12,
10
"payload": {
11
"method": "account/rateLimits/updated",
12
"params": {
13
"rateLimits": {
14
"limitId": "codex",
15
"limitName": null,
16
"primary": null,
17
"secondary": null,
18
"credits": null,
19
"planType": 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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
errorReports a native error and whether Codex intends to retry it.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "error",
12
"params": {
13
"threadId": "thread_example",
14
"turnId": "native_turn_example",
15
"error": {
16
"message": "The model request timed out."
17
},
18
"willRetry": true
19
}
20
},
21
"tools": null,
22
"tokens_info": null,
23
"cost": null,
24
"duration": null,
25
"model": null,
26
"created_at": "2026-09-10T14:00:00Z"
27
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
turn/completedReports a native turn ending with status completed, failed, or interrupted.
Link to this event

Command item/completed notifications can arrive after this native event. When the agent finishes a message, Ellipsis waits up to two seconds for pending command notifications before emitting the platform message_ended record. Commands left running in the background do not keep the message 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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"method": "turn/completed",
12
"params": {
13
"threadId": "thread_example",
14
"turn": {
15
"id": "native_turn_example",
16
"status": "completed",
17
"items": [],
18
"error": null
19
}
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
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
type = "subAgentActivity"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "subAgentActivity".
kindstringRequired
agentPathstring | nullOptional
agentThreadIdstringRequired
idstringRequired
type = "collabAgentToolCall"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "collabAgentToolCall".
idstringRequired
promptstring | nullOptional
receiverThreadIdsarray<string>Required
Fields and variants
[]string
senderThreadIdstringRequired
statusstringRequired
Allowed values: "inProgress", "completed", "failed".
toolstringRequired
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string

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

item/agentMessage/delta supplies live delta frames 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.

Gemini CLI

Gemini CLI records use source: "gemini", record_format: "gemini_stream_json@1", and kind: "gemini". record_type is the native payload.type. It is init once per agent process, message for the user message echo and each assistant message, tool_use and tool_result for a tool call and its outcome paired by tool_id, error for a non-fatal error, and result when the turn ends, carrying the turn's token counts under stats. Assistant text streams through delta frames and is stored once per message.

WebSocket frames

Connect using the Python SDK or TypeScript SDK. The public endpoint is wss://api.ellipsis.dev/v1/sessions/{id}/stream. Authenticate with a bearer token.

Each WebSocket message contains one frame. The first frame is session. records 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. List records reports earliest_feed_seq. History before it is no longer retained.

recordsDelivers a batch of retained or newly produced records in feed_seq order.
Link to this event

Example JSON

1
{
2
"type": "records",
3
"records": [
4
{
5
"kind": "platform",
6
"source": "lifecycle",
7
"record_format": "ellipsis_lifecycle@1",
8
"record_type": "message_started",
9
"id": "record_example",
10
"session_id": "session_example",
11
"message_id": "message_example",
12
"feed_seq": 12,
13
"payload": {
14
"message_id": "message_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:00Z"
22
}
23
]
24
}

Field specification

typestringRequired
Must be "records".
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.
sessionThe whole session. It is the first frame and is resent whenever its public fields change, including the status, the error, and cost. A closed status is the last frame.
Link to this event

Example JSON

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

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, codex, or gemini. 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 message, waiting for one.
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, codex, or gemini. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Reasoning effort for every message. 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 message, waiting for one.
conversationobjectRequired
Additional properties are not allowed.
Fields and variants
interactivebooleanRequired
Whether the session stays open after its first message is answered. 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.
validateobject | string | nullRequired
Check that the environment works, for example that required tools are on PATH. Runs last, after before_start, each time a session starts or resumes and each time the environment is built after a change. A nonzero exit fails the session or the build. Not cached. 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
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
geminiobject | nullRequired
Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini. Additional properties are not allowed.
Fields and variants
modelstringRequired
The model the session runs on: a Gemini id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no message, waiting for one.
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", "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".
enabledbooleanRequired
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: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale".
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
check_suiteobject | nullRequired
Additional properties are not allowed.
Fields and variants
appsarray<string>Required
Fields and variants
[]string
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
onarray<string>Required
Fields and variants
[]string
Allowed values: "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure".
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
enabledbooleanRequired
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.
statusobject | 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: "pending", "passed", "failed", "errored".
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
workflow_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: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure".
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
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
budgetintegerRequired
The spend budget enforced for this session, in millicents, after resolving defaults and ceilings.
claude_codeobject | nullRequired
Claude Code input and native options. Set exactly one of claude_code, codex, or gemini. 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 message, waiting for one.
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, codex, or gemini. Additional properties are not allowed.
Fields and variants
effortstring | nullRequired
Reasoning effort for every message. 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 message, waiting for one.
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 message is answered.
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
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. Additional properties are allowed.
Fields and variants
chargedintegerRequired
What Ellipsis charged to credit, in millicents. It is everything except subscription tokens.
cpuintegerRequired
CPU spend in millicents.
feeintegerRequired
Platform fee in millicents.
llmobjectRequired
LLM token cost, in total and by model, split by who paid. Additional properties are allowed.
Fields and variants
allobjectRequired
Token cost across every model. Additional properties are allowed.
Fields and variants
claude_subscriptionintegerRequired
Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
codex_subscriptionintegerRequired
Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
platformintegerRequired
Token cost charged to Ellipsis credit, in millicents.
totalintegerRequired
All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
by_modelarray<object>Required
Token cost for each model that used tokens.
Fields and variants
[]object
Additional properties are allowed.
Fields and variants
claude_subscriptionintegerRequired
Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
codex_subscriptionintegerRequired
Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
modelstringRequired
The model that used these tokens.
platformintegerRequired
Token cost charged to Ellipsis credit, in millicents.
totalintegerRequired
All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
memoryintegerRequired
Memory spend in millicents.
totalintegerRequired
Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps.
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.
validateobject | string | nullRequired
Check that the environment works, for example that required tools are on PATH. Runs last, after before_start, each time a session starts or resumes and each time the environment is built after a change. A nonzero exit fails the session or the build. Not cached. 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
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
errorobject | nullRequired
Why the last message failed, was stopped, or was cancelled; null otherwise. Additional properties are allowed.
Fields and variants
detailstring | nullRequired
A human-readable explanation.
reasonstringRequired
What went wrong. 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", "stopped".
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: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale".
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.check_suite"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.check_suite".
actionstringRequired
Allowed values: "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
appstring | nullRequired
branchstring | nullRequired
conclusionstring | nullRequired
head_shastringRequired
pull_request_numberinteger | nullRequired
repositorystringRequired
urlstringRequired
type = "github.workflow_run"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.workflow_run".
actionstringRequired
Allowed values: "requested", "queued", "waiting", "pending", "started", "passed", "failed", "timed_out", "cancelled", "skipped", "neutral", "action_required", "stale", "startup_failure".
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
run_numberintegerRequired
urlstringRequired
type = "github.status"object
Additional properties are allowed.
Fields and variants
typestringRequired
Must be "github.status".
actionstringRequired
Allowed values: "pending", "passed", "failed", "errored".
actorobject | nullRequired
Additional properties are allowed.
Fields and variants
avatar_urlstring | nullRequired
is_botboolean | nullRequired
namestringRequired
branchstring | nullRequired
contextstringRequired
head_shastringRequired
pull_request_numberinteger | nullRequired
repositorystringRequired
statestringRequired
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
Allowed values: "commented", "delegated".
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
geminiobject | nullRequired
Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini. Additional properties are not allowed.
Fields and variants
modelstringRequired
The model the session runs on: a Gemini id from the models table. Required.
promptstring | nullRequired
The initial user message, passed verbatim. Omit to start an interactive session with no message, waiting for one.
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 session's structured output: the `json_schema` the agent must satisfy and, once the agent has submitted it, the `result`. Additional properties are allowed.
Fields and variants
json_schemaobjectRequired
JSON Schema the agent's result must satisfy. Additional properties are allowed.
resultobject | nullRequired
The payload the agent submitted, or null until it submits one. 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", "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
statusstringRequired
Where the session is. A message you sent is answered once the status is `idle` or `closed`; its `message_ended` record in GET /v1/sessions/{id}/records says how. Allowed values: "queued", "preparing", "running", "idle", "closed".
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 has used so far. Additional properties are allowed.
Fields and variants
allobjectRequired
Token counts across every model. 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.
outputintegerRequired
Output tokens used.
totalintegerRequired
All tokens used, including prompt cache reads and writes. Token cost is priced on this.
by_modelarray<object>Required
Token counts for each model that used tokens.
Fields and variants
[]object
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 that used these tokens.
outputintegerRequired
Output tokens used.
totalintegerRequired
All tokens used, including prompt cache reads and writes. Token cost is priced on this.
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
"message_id": "message_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.
message_idstring | nullRequired
Identifier of the message being answered, if known.
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.
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
"message_id": "message_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.
message_idstring | nullRequired
Identifier of the message being answered, if known.
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.
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.
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 message ends, or a reconnect supplies a new session frame. 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 session stays connected between messages. When the session closes, a session frame with status closed is the last frame, followed by a normal socket close. The message you sent is answered when a session frame shows status idle or closed. 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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"kind": "system",
12
"subtype": "init",
13
"data": {
14
"model": "claude-opus-5-5"
15
},
16
"session_id": "11111111-1111-4111-8111-111111111111"
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
userCarries a historical user prompt or tool-result content.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"kind": "user",
12
"content": "Run the tests and report failures."
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
assistantCarries historical assistant content with its model at the payload root.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"kind": "assistant",
12
"model": "claude-opus-5-5",
13
"content": [
14
{
15
"type": "text",
16
"text": "All 12 tests passed."
17
}
18
]
19
},
20
"tools": null,
21
"tokens_info": null,
22
"cost": null,
23
"duration": null,
24
"model": "claude-opus-5-5",
25
"created_at": "2026-09-10T14:00:00Z"
26
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
resultReports a historical turn outcome with cost_usd rather than the native total_cost_usd field.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"kind": "result",
12
"subtype": "success",
13
"is_error": false,
14
"num_turns": 1,
15
"duration_ms": 4200,
16
"duration_api_ms": 3100,
17
"result": "All 12 tests passed.",
18
"cost_usd": 0.01
19
},
20
"tools": null,
21
"tokens_info": null,
22
"cost": 1000,
23
"duration": 4200,
24
"model": null,
25
"created_at": "2026-09-10T14:00:00Z"
26
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
rate_limitReports historical rate-limit information with snake_case fields.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"kind": "rate_limit",
12
"status": "allowed",
13
"rate_limit_type": "five_hour",
14
"utilization": 0.25,
15
"resets_at": 1789066800
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_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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string

Codex JSONL records

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

thread.startedAnnounces the historical native thread identifier.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "thread.started",
12
"thread_id": "thread_example"
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
turn.startedAnnounces a historical native turn beginning.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "turn.started"
12
},
13
"tools": null,
14
"tokens_info": null,
15
"cost": null,
16
"duration": null,
17
"model": null,
18
"created_at": "2026-09-10T14:00:00Z"
19
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
item.startedAnnounces a historical conversation item beginning.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "item.started",
12
"item": {
13
"id": "command_example",
14
"type": "command_execution",
15
"command": "pytest -q",
16
"status": "in_progress",
17
"aggregated_output": ""
18
}
19
},
20
"tools": [
21
"Bash"
22
],
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".
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
item.updatedSupplies an update to an existing historical item.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "item.updated",
12
"item": {
13
"id": "command_example",
14
"type": "command_execution",
15
"command": "pytest -q",
16
"status": "in_progress",
17
"aggregated_output": "Running 12 tests..."
18
}
19
},
20
"tools": [
21
"Bash"
22
],
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".
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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
item.completedSupplies a historical item's completed content or outcome.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "item.completed",
12
"item": {
13
"id": "command_example",
14
"type": "command_execution",
15
"command": "pytest -q",
16
"status": "completed",
17
"aggregated_output": "12 passed",
18
"exit_code": 0
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.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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
turn.completedReports successful historical turn completion and usage.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "turn.completed",
12
"usage": {
13
"input_tokens": 1200,
14
"output_tokens": 80,
15
"cached_input_tokens": 0
16
}
17
},
18
"tools": null,
19
"tokens_info": {
20
"input_tokens": 1200,
21
"output_tokens": 80,
22
"cache_read_input_tokens": 0,
23
"cache_creation_input_tokens": 0,
24
"num_turns": 0,
25
"cost_usd": 0
26
},
27
"cost": null,
28
"duration": null,
29
"model": null,
30
"created_at": "2026-09-10T14:00:00Z"
31
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
turn.failedReports a failed historical turn with its error.
Link to this event

Example JSON

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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "turn.failed",
12
"error": {
13
"message": "The model request timed out."
14
}
15
},
16
"tools": null,
17
"tokens_info": null,
18
"cost": null,
19
"duration": null,
20
"model": null,
21
"created_at": "2026-09-10T14:00:00Z"
22
}

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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string
errorReports a historical native 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
"message_id": "message_example",
9
"feed_seq": 12,
10
"payload": {
11
"type": "error",
12
"message": "The model request timed out."
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 "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.
message_idstring | nullRequired
The message this record belongs to: the message itself, or what happened while answering it. Null for records outside any message, such as the session closing.
modelstring | nullRequired
session_idstringRequired
Session containing this record.
tokens_infoobject | nullRequired
Additional properties are not allowed.
Fields and variants
cache_creation_input_tokensintegerOptional
cache_read_input_tokensintegerOptional
cost_usdnumberOptional
input_tokensintegerOptional
num_turnsintegerOptional
output_tokensintegerOptional
toolsarray<string> | nullRequired
Fields and variants
[]string

Unknown records

A record with kind: "unknown" retains its original source, record_format, record_type, and JSON payload. This includes new native methods, new content variants, 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 CodeCodexGemini CLIWebSocket framesHistorical formatsClaude SDK recordsCodex JSONL recordsUnknown records
Schedule a demo