events

Every open alarm in a scope, oldest first, stably paged (the rail's open list)

Pages through EVERY open alarm (the queue's own membership) at one site, optionally narrowed to camera_ids, oldest first on (created_at, id) with an opaque cursor. Unlike GET /operator/events/all (newest first, offset-paged, 1,000 by default) an old urgent alarm can never sit beyond the first page, and closes or arrivals between pages cannot duplicate or skip rows. Page 1 pins snapshot.as_of; every page of the pass bounds membership by CREATION time (created_at <= as_of, immutable per alarm) and by current membership at that page's own read (still open, unexpired, queue-visible). An alarm that was open at as_of and still is when its page runs is therefore always returned, even if a late AI verdict re-stamps its queued_at. Alarms created after as_of are the push stream's and the next pass's. Late visibility: an alarm created at or before as_of that only becomes visible to the queue after it (a late verdict or failsafe flip) is returned if its key is still ahead of the cursor, otherwise it is the push stream's and the next pass's. status is more (continue), complete (last page; complete as of as_of under these rules) or truncated (the pass ceiling was hit; omitted is the count of eligible alarms after the last returned one at that read, at least that many when omitted_capped). counts are PAGE-ONE observations: the scalar totals (scope_total, site_total), the exact overdue counts by age_marks and oldest_queued_at repeat unchanged from page one on every later page, while by_camera is returned on page one only (null afterwards). The rows returned over a pass can exceed the totals (late-visible alarms) or fall short of them (closes). Each row carries queued_at (age = snapshot.server_time - queued_at) and its live claim. A 200 is always a true statement; anything else (404 unknown or out-of-scope site or any invisible camera, one answer; 403 customer roles; 422 CURSOR_INVALID for an invalid cursor, 422 CURSOR_EXPIRED for an expired one (restart from page 1); 503 deadline or database failure) is UNKNOWN, never an empty list. Central staff only, tenant-scoped in SQL on every page. Read-only: it stamps no first view and takes no claim. Capability: open_alarms_paged_read on GET /auth/me.

get/events/open-alarms

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/events/open-alarms
  • Auth
    HTTP bearer

Query parameters

site_idstring uuid required

The site

camera_idstring[] nullable

Narrow to these cameras (repeat the parameter; at most 50). Absent = the whole site.

limitinteger

Rows per page

cursorstring nullable

next_cursor from the previous page; absent = a new pass. An invalid cursor is 422 CURSOR_INVALID, an expired one 422 CURSOR_EXPIRED

age_marksstring nullable

Page 1: comma list of 1 to 3 overdue marks in seconds for counts.older_than (default 30,60). Later pages retain page one's counters; this parameter may be omitted and does not change them.

Response

Successful Response

status'more' | 'complete' | 'truncated' required

more: this page is fine and next_cursor continues the pass. complete: the last page; nothing after it in scope as of snapshot.as_of. truncated: the pass hit limits.pass_ceiling; the eligible rows counted in omitted will NOT be returned (the oldest are always the ones returned).

order'oldest_first'

Page order is (created_at, id) ascending; sort loaded rows by (queued_at, id)

next_cursorstring nullable

Opaque; send it back with the same parameters. Null on the last page. An invalid cursor is 422 CURSOR_INVALID, an expired one 422 CURSOR_EXPIRED

omittedinteger nullable

Set only when truncated: the eligible rows after the last returned key at this read (the page's own filters and keyset), at least this many when omitted_capped. A read-time count, not page 1's total minus the rows returned.

omitted_cappedboolean

True when the bounded remainder count hit its cap (10,000): omitted is then a lower bound. Always false unless truncated.

Changes

No recorded changes to this operation across all 2 revisions of this API.