Skip to content
Extrovert Extrovert Docs

Long-poll for a review event

GET
/v1/reviews/events/wait

Long-poll (~25–55s) that blocks until a new review nudge is available OR the deadline elapses, then returns like list_review_events (empty events on timeout, never an error). Cancel-safe: a client disconnect returns promptly. Customer-scoped.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
review_id
string

Restrict the wait to one review’s events (rr_…).

wait_seconds
integer

Long-poll budget in seconds (default ~30, capped ~55).

limit
integer
default: 50 >= 1 <= 100

Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Ok

The drain result for list_review_events / wait_for_review_event; un-acked events in FIFO seq order plus the per-review cursors.

object
events
required
Array<object>

One durable review nudge (ndg_…) as drained from the authoritative liveness queue (spec §11). seq is the per-review monotonic ordinal the ack cursor advances against (0 for a broadcast nudge). Opaque typed ids only (D10).

object
seq
required
integer
id
required
string
reason
required

The work-item kind. sent / send_failed / cancelled are TERMINAL: the LAST event a review ever produces is one of these; ack it and stop polling that review. (Almost every review emits exactly one; a failed send the agent then closes out emits send_failed and then cancelled.) sent covers both delivery flavors; payload.state distinguishes sent from auto_sent. approved and staleness are RESERVED and never emitted (kept so the enum is never narrowed). Treat an unrecognized reason as ack-and-ignore: this enum is additive across 0.x releases.

string
Allowed values: redraft_requested feedback_added recheck_category staleness approved rejected front_run_next rule_changed propagate_general_rule sent send_failed cancelled
review_id
string
category_id
string
payload
object
key
additional properties
any
created_at
required
string format: date-time
cursors
Array<object>

The agent’s per-(agent, review) ack frontier; its strict-FIFO position for one review.

object
review_id
required
string
last_acked_seq
required
integer

401

Section titled “401 ”

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope

403

Section titled “403 ”

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope