Struct EventLogReadRequest 

pub struct EventLogReadRequest {
    pub agent_ids: Option<Vec<String>>,
    pub agent_scope: Option<EventsAgentScope>,
    pub cursor: Option<String>,
    pub direction: Option<EventsReadDirection>,
    pub include_ephemeral: Option<bool>,
    pub max: Option<i64>,
    pub types: Option<Value>,
    pub wait_ms: Option<i32>,
}

Cursor, batch size, and optional long-poll/filter parameters for reading session events.

Experimental. This type is part of an experimental wire-protocol surface and may change or be removed in future SDK or CLI releases.

Fields

agent_ids: Option<Vec<String>>

Optional non-empty list of subagent identifiers. When provided, only events owned by one of these agents are returned; ownership recognizes the event envelope’s agentId plus legacy data.agentId and data.parentToolCallId markers. This filter takes precedence over agentScope.

agent_scope: Option<EventsAgentScope>

Agent-scope filter: ‘primary’ returns only main-agent events plus events whose type starts with ‘subagent.’ (matching the typed-subscription default behavior); ‘all’ returns events from all agents (matching wildcard-subscription behavior). Default is ‘all’ to preserve wildcard semantics for catch-up callers.

cursor: Option<String>

Opaque cursor returned by a previous read. Omit on the first call to start from the beginning of the session’s persisted history.

direction: Option<EventsReadDirection>

Direction to page through the session’s persisted event history. ‘forward’ (default) pages from the cursor toward newer events (or from the start of history when no cursor is given). ‘backward’ enables tail-first reads: with no cursor it returns the NEWEST max events, and the returned cursor pages toward OLDER events on subsequent backward reads. Events within a returned batch are always in chronological (oldest-to-newest) order, even for a backward read. Backward reads cover PERSISTED history only; ephemeral events are never returned by a backward read. direction selects the INITIAL read only: the returned cursor is self-describing, so a continuation read pages in the cursor’s own direction regardless of the direction passed alongside it — a forward cursor always pages forward and a backward cursor always pages backward. Pass the direction that matches the cursor to avoid confusion.

include_ephemeral: Option<bool>

When false, skip ephemeral events entirely and return only durable (persisted) events. History-backfill callers that discard ephemerals anyway should set this so the read is bounded by the durable log length instead of racing the ephemeral ring on a busy session. Defaults to true (ephemerals are interleaved with durable events in creation order). Ignored by backward reads, which always cover persisted history only.

max: Option<i64>

Maximum number of events to return in this batch (1–1000, default 200).

types: Option<Value>

Either ‘*’ to receive all event types, or a non-empty list of event types to receive

wait_ms: Option<i32>

Milliseconds to wait for new events when the cursor is at the tail of history. 0 (default) returns immediately even if no events are available. Capped at 30000ms. Ephemeral events that arrive during the wait are delivered in this batch but are NOT replayable on a subsequent read (use a non-zero waitMs in your next call to capture future ephemerals as they happen). This applies to forward reads only: a backward read always returns immediately and ignores waitMs, because backward paging covers persisted history only while new events append at the tail (the opposite end from a backward page), so no blocking or ephemeral delivery can occur.

Trait Implementations

impl Clone for EventLogReadRequest

fn clone(&self) -> EventLogReadRequest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EventLogReadRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for EventLogReadRequest

fn default() -> EventLogReadRequest

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for EventLogReadRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for EventLogReadRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.