Skip to navigation
Runtype APIEvents

Poll product events

Reads your organization’s product events in cursor order. Omit after to start from now: the response carries no events and the current cursor. Pass the returned cursor back as after on the next call. waitMs holds the request open until an event arrives or the wait ends (at most 50000 ms). Events are kept for seven days.

Authentication

AuthorizationBearer
API key or Clerk session token

Query parameters

namestringOptional1-80 characters

One event type from GET /v1/events/types; omit for every type

afterstringOptionalformat: "^(0|[1-9]\d{0,18})$"

Decimal cursor; events after it are returned

maxAgeMsinteger or nullOptional0-604800000
Skip events older than this many milliseconds
maxEventsintegerOptional1-200
Page size, default 50
waitMsinteger or nullOptional0-50000

Long-poll: wait up to this long for a matching event

agentIdstringOptional1-255 characters
Only events for this agent
flowIdstringOptional1-255 characters
Only events for this flow
productIdstringOptional1-255 characters
Only events inside this product
surfaceIdstringOptional1-255 characters
Only events on this surface
scheduleIdstringOptional1-255 characters
Only events for this schedule
suiteIdstringOptional1-255 characters
Only events for this eval suite
taskIdstringOptional1-255 characters
Only events for this delegated task
onlyRegressionsenumOptional

Eval runs only: keep runs whose pass rate dropped

Allowed values:
minIntervalMsinteger or nullOptional0-86400000

Execution failures only: coalesce repeats within this window

Response

Events after the cursor
cursorstring or nullformat: "^(0|[1-9]\d{0,18})$"

Pass back as after: after the last returned event, or the head when none

eventslist of objects
hasMoreboolean

More events matched beyond maxEvents; poll again now

nextPollMsinteger
Suggested wait before the next poll
truncatedboolean

True when after predates retention or maxAgeMs, so events were skipped

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error