List events (JSON)

GET

/v1/sessions/{session_id}/events

• Production API

Returns events for a session as a JSON array. Supports filtering by event type via types (positive: only these types) and exclude (negative: remove these types). When both are provided, types narrows first, then exclude removes from that set. Both accept only known event types (max 25 per parameter). Unknown types return 400.

Parameters

Path Parameters

session_id

required

string

Session ID (prefixed, e.g., sess_…)

Query Parameters

since_id

One of:

null

null

string

Prefixed identifier with ‘agent’ prefix

string

/^agent_[0-9a-f]{32}$/

Example

agent_01933b5a00007000800000000000001

Filter events with ID greater than this event ID (prefixed format: event_{32-hex})

types

Array<string>

Positive type filter: only return events matching these types (can be specified multiple times). When empty, all types are returned. Example: ?types=turn.started&types=turn.completed

exclude

Array<string>

Event types to exclude from the response (can be specified multiple times). Applied after types filter. Common delta events to exclude: output.message.delta, reason.thinking.delta

Responses

200

Events list

Response wrapper for list endpoints. All list endpoints return responses wrapped in a data field.

object

data

required

Array of items returned by the list operation.

Array<object>

Standard event following the Everruns event protocol.

All events have a consistent structure:

• id: Unique event identifier (format: event_{32-hex})
• type: Event type in dot notation (e.g., “input.message”, “reason.started”)
• ts: ISO 8601 timestamp with millisecond precision
• session_id: Session this event belongs to (format: session_{32-hex})
• context: Correlation context for tracing
• data: Event-specific payload (typed via EventData enum)
• metadata: Optional arbitrary metadata
• tags: Optional list of tags for filtering

object

context

required

Correlation context

object

exec_id

Atom execution identifier

string | null

Example

exec_01933b5a00007000800000000000001

input_message_id

User message that triggered this turn

string | null

Example

message_01933b5a00007000800000000000001

parent_span_id

Parent span ID for hierarchical linking (OTel-style). Links this span to its parent in the trace hierarchy.

string | null

span_id

This event’s span ID for observability (OTel-style). Uniquely identifies this span within the trace.

string | null

trace_id

Trace ID for observability (OTel-style). Groups related spans into a single trace. For agent turns, this is typically the turn_id string.

string | null

turn_id

Turn identifier (for turn-scoped events)

string | null

Example

turn_01933b5a00007000800000000000001

data

required

One of:

object

Data for input.message event

object

message

required

The user message

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

unknown

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

unknown

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

object

Data for output.message.delta event

Incremental text update during LLM generation. Events are batched (~100ms) to reduce volume while providing real-time feedback.

object

accumulated

required

Accumulated text so far

string

delta

required

The new text chunk

string

turn_id

required

Turn ID this delta belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for output.message.started event

Emitted when the LLM starts generating a response. UI can show a “thinking” indicator until output.message.delta or output.message.completed events arrive.

object

model

Optional model name being used

string | null

turn_id

required

Turn ID this output belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for output.message.completed event

object

message

required

The agent message

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

unknown

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

unknown

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

metadata

One of:

null

null

object

Metadata about the model used

object

model

required

Model name (e.g., “gpt-4o”, “claude-3-sonnet”)

string

model_id

Model ID (internal identifier)

string | null format: uuid

provider_id

Provider ID (internal identifier)

string | null format: uuid

usage

One of:

null

null

object

Token usage

object

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for turn.started event

object

input_content

Input message content (for observability)

string | null

input_message_id

required

Input message ID that triggered this turn

string

Example

message_01933b5a00007000800000000000001

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

object

Data for turn.completed event

object

duration_ms

Duration in milliseconds

integer | null format: int64

input_content

Input message content (for observability, passed through from turn.started)

string | null

iterations

required

Number of iterations in this turn

integer format: int32

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Aggregated token usage for all LLM calls in this turn

object

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for turn.failed event

object

error

required

Error message

string

error_code

Error code

string | null

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.started event

object

agent_id

One of:

null

null

string

Agent ID being used (optional)

string

/^agent_[0-9a-f]{32}$/

Example

agent_01933b5a00007000800000000000001

harness_id

required

Harness ID being used

string

/^agent_[0-9a-f]{32}$/

Example

agent_01933b5a00007000800000000000001

metadata

One of:

null

null

object

Metadata about the model being used

object

model

required

Model name (e.g., “gpt-4o”, “claude-3-sonnet”)

string

model_id

Model ID (internal identifier)

string | null format: uuid

provider_id

Provider ID (internal identifier)

string | null format: uuid

object

Data for reason.completed event

object

duration_ms

Duration of the reason phase in milliseconds

integer | null format: int64

error

Error message if failed

string | null

has_tool_calls

required

Whether tool calls were requested

boolean

success

required

Whether the LLM call succeeded

boolean

text_preview

Text response preview (first 200 chars)

string | null

tool_call_count

required

Number of tool calls requested

integer format: int32

usage

One of:

null

null

object

Token usage from the LLM call

object

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for act.started event

object

tool_calls

required

Tool calls to be executed

Array<object>

Summary of a tool call (compact form without arguments)

object

display_name

Human-readable display name for UI rendering

string | null

id

required

string

name

required

string

object

Data for act.completed event

object

completed

required

Whether all tool calls completed

boolean

duration_ms

Duration of the act phase in milliseconds

integer | null format: int64

error_count

required

Number of failed tool calls

integer format: int32

success_count

required

Number of successful tool calls

integer format: int32

object

Data for tool.started event

object

display_name

Human-readable display name for UI rendering

string | null

tool_call

required

The tool call being executed

object

arguments

required

Arguments as JSON

object

id

required

Unique ID for this tool call

string

name

required

Tool name to execute

string

object

Data for tool.completed event

object

display_name

Human-readable display name for UI rendering

string | null

duration_ms

Duration of the tool call in milliseconds

integer | null format: int64

error

Error message if failed

string | null

result

Result content (for successful calls)

array | null

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

unknown

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

unknown

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

status

required

Status: “success”, “error”, “timeout”, “cancelled”

string

success

required

Whether the tool call succeeded

boolean

tool_call_id

required

Tool call ID

string

tool_name

required

Tool name

string

object

Data for tool.call_requested event

Emitted when the agent needs client-side tool calls executed. The workflow pauses until the client submits results via the API.

object

tool_calls

required

Tool calls that need to be executed by the client

Array<object>

Tool call from LLM response

object

arguments

required

Arguments as JSON

object

id

required

Unique ID for this tool call

string

name

required

Tool name to execute

string

object

Data for llm.generation event

Emitted after each LLM API call to provide full visibility into the messages sent to the model and the response received.

object

messages

required

Messages sent to the LLM (including system prompt)

Array<object>

A message in the conversation

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

unknown

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

unknown

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

metadata

required

Metadata about the generation

object

compaction

One of:

null

null

object

Compaction information if context was compressed before generation Occurs when the conversation context exceeded the model’s limit

object

compacted

required

Whether compaction was performed

boolean

duration_ms

Duration of the compaction operation in milliseconds

integer | null format: int64

input_tokens_after

Number of input tokens after compaction

integer | null format: int32

input_tokens_before

Number of input tokens before compaction

integer | null format: int32

duration_ms

Duration of the generation in milliseconds

integer | null format: int64

error

Error message if generation failed

string | null

finish_reasons

Finish reasons from the LLM (e.g., [“stop”], [“tool_calls”]) Required for gen-ai semantic conventions

array | null

model

required

Model identifier used for generation

string

provider

Provider type (openai, anthropic, etc.)

string | null

response_id

Unique response identifier from the LLM provider Required for gen-ai semantic conventions

string | null

retry

One of:

null

null

object

Retry information if rate limit retries occurred Contains number of retries and total wait time

object

attempts

required

Number of retry attempts made (0 = succeeded on first try)

integer format: int32

total_wait_ms

required

Total time spent waiting between retries in milliseconds

integer format: int64

success

required

Whether the generation was successful

boolean

time_to_first_token_ms

Time to first token in milliseconds (streaming latency)

integer | null format: int64

usage

One of:

null

null

object

Token usage statistics

object

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

output

required

Output from the LLM

object

text

Text response from the model

string | null

tool_calls

Tool calls requested by the model

Array<object>

Tool call from LLM response

object

arguments

required

Arguments as JSON

object

id

required

Unique ID for this tool call

string

name

required

Tool name to execute

string

tools

Tools available to the LLM for this generation

Array<object>

Summary of a tool definition (compact form for events)

object

description

required

Tool description

string

display_name

Human-readable display name for UI rendering

string | null

name

required

Tool name

string

object

Data for reason.thinking.delta event (extended thinking content from models like Claude)

This event streams incremental thinking/reasoning content from models that support extended thinking mode (e.g., Claude with thinking enabled). The thinking content represents the model’s chain-of-thought reasoning before producing the final response.

object

accumulated

required

Accumulated thinking text so far (convenience for UI)

string

delta

required

The thinking delta (new thinking text since last delta)

string

turn_id

required

Turn ID this delta belongs to (for correlation)

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.thinking.started event

Emitted when extended thinking begins during reasoning phase. This signals the model is using chain-of-thought reasoning. UI can show a “thinking” indicator.

object

model

Optional model name being used

string | null

turn_id

required

Turn ID this thinking belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.thinking.completed event

Emitted when extended thinking completes and the model transitions to producing the final response. Contains the complete thinking content.

object

thinking

required

Complete thinking content

string

turn_id

required

Turn ID this thinking belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for turn.cancelled event

object

reason

Reason for cancellation

string | null

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Token usage before cancellation (if available)

object

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for session.started event

object

agent_id

Agent ID (optional)

string | null

Example

agent_01933b5a00007000800000000000001

harness_id

required

Harness ID

string

Example

harness_01933b5a00007000800000000000001

model_id

Model ID if specified

string | null

Example

model_01933b5a00007000800000000000001

object

Data for session.activated event (turn started, session now active)

object

input_message_id

required

Input message ID that triggered the turn

string

Example

message_01933b5a00007000800000000000001

turn_id

required

Turn ID that activated the session

string

Example

turn_01933b5a00007000800000000000001

object

Data for session.idled event (turn completed, session now idle)

object

iterations

Number of iterations in the completed turn

integer | null format: int32

turn_id

required

Turn ID that just completed

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Cumulative token usage for the session at this point

object

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

id

required

Unique event identifier (format: event_{32-hex})

string

Example

event_01933b5a00007000800000000000001

metadata

Arbitrary metadata for the event

sequence

Sequence number within session (for ordering)

integer | null format: int32

session_id

required

Session this event belongs to (format: session_{32-hex})

string

Example

session_01933b5a00007000800000000000001

tags

Tags for filtering and categorization

array | null

ts

required

Event timestamp

string format: date-time

type

required

Event type in dot notation

string

400

Invalid session ID or invalid event type filter

404

Session not found

500

Internal server error