Skip to main content
GET
List run events

Authorizations

Authorization
string
header
required

Use a JWT bearer token or a Veryfront API key in the Authorization header.

Path Parameters

run_id
string
required

Canonical run UUID. Normal callers need access to the run owner and project.runs.read. A bound eval runtime may instead read its authorized direct agent child.

Minimum string length: 1

Query Parameters

event_representation

Use run-events-v1 to receive Agent Events Protocol CloudEvents with opaque page cursors. Omit it to keep the released run-event row contract.

Available options:
run-events-v1
cursor
string

Opaque page_info.next cursor. Reuse it with the same filters, sort order and descendant scope. The previous page’s continuation cursor. Released row reads use a positive event_id. With event_representation=run-events-v1, this is the opaque page_info.next_cursor token from the previous target page.

limit
string<int32>
default:20

Maximum number of records in a page, from 1 to 100. Defaults to 20.

Pattern: ^\d+$
sort_order
default:asc

Event order by durable event id. asc returns older events first; desc returns newer events first. Defaults to asc.

Available options:
asc,
desc
event_class

The event class associated with this record. Event class to include: fact for state changes or delta for streaming fragments. If omitted, returns both.

Available options:
fact,
delta
event_type

Filter by event_type. Repeat the query parameter for multiple values; comma-separated values remain a compatibility alias. Values within this filter use OR; different filters use AND.

Maximum array length: 32
is_error

If true, returns only events with is_error: true. If false, returns other events. If omitted, returns both.

Available options:
true,
false
start

Only events created at or after this instant (ISO 8601 with a UTC offset, inclusive). A summary bucket start can be sent as is.

end

Only events created before this instant (ISO 8601 with a UTC offset, exclusive). Must be later than start. A summary bucket end can be sent as is.

span_id

Only events whose envelope span_id, as served to the caller, is exactly this value (tool:, message:, step:, input_request:, run:, with a non-empty ).

Minimum string length: 1
turn_id

Only events whose envelope turn_id, as served to the caller, is exactly this value (message:, with a non-empty ).

Minimum string length: 1
search

Case-insensitive substring of the event payload JSON as served to the caller (1-200 characters after trimming, matched literally).

Required string length: 1 - 200
include_descendants
default:false

If true, includes events from readable descendant runs, up to 16 generations. Results share one event_id order and cursor. Each event retains its run_id and the payload visibility permitted for that run. Runs the caller cannot read are excluded. Defaults to false.

If at least one descendant is included, task or workflow runs without stored events do not contribute synthetic lifecycle events. Event IDs are allocated before commit. During active writes, ascending pagination can pass an ID that another run commits later.

Available options:
true,
false
after_event_id
Required range: -9007199254740991 <= x <= 9007199254740991
cursor_profile
enum<string>
Available options:
run-events-descendants-v1

Response

Run events. Editors read diagnostic payloads; viewers read public ones.

data
object[]
required
page_info
object
required

Opaque cursor for the next page; null means there are no more results.