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
Minimum string length: 1

Query Parameters

cursor
string

The previous page’s page_info.next event ID, excluded from the next page. With sort_order=asc, returns larger IDs; with sort_order=desc, returns smaller IDs. If omitted, starts at the oldest event for ascending order or the newest for descending order.

limit
integer
default:100

Most events per page (1-500, default 100).

Required range: 1 <= x <= 500
sort_order
enum<string>
default:asc

Event order. asc returns oldest first; desc returns newest first. Defaults to asc.

Available options:
asc,
desc
after_event_id
integer | null

Deprecated. Use cursor. Accepted as an ascending cursor; 0 means no cursor.

Required range: 0 <= x <= 9007199254740991
errors_only
enum<string>

Deprecated. Use is_error=true. errors_only=true cannot be combined with is_error=false.

Available options:
true,
false
event_class
enum<string>

Event class to include: fact for state changes or delta for streaming fragments. If omitted, returns both.

Available options:
fact,
delta
event_type

Only events of these canonical types (comma-separated, repeatable, at most 32). A legacy-spelled stored row matches under the type it is served as.

is_error
enum<string>

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

Available options:
true,
false
start
string<date-time>

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
string<date-time>

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
string

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
string

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

Minimum string length: 1

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
enum<string>
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
format
enum<string>

Deprecated and ignored. Accepts only typed, which is the response format already used. Other values are rejected. This parameter will be removed when the alias is retired.

Available options:
typed

Response

200 - application/json

Run events

data
object[]
required
page_info
object
required