Returns a list of notifications that the user has access to.
Two ways to page through results, and every response supports switching into the second one:
- Offset (
page/per-page): the default, ordered byupdatedAtdescending unlesssortis given. Simple, butpage=Ncan duplicate or skip rows if the underlying data changes between requests (e.g. an in-progress infinite scroll while ingest is running) — the sort key is mutable. - Cursor (
cursor, from a previous response'snextCursor): stable under concurrent mutation — anchors on the previous page's last row rather than a row offset, so an insert or update elsewhere in the result set can't shift the boundary.currentPageis not meaningful in this mode (always1);cursorandpagecannot both be set (422). A cursor is scoped to the sort/filter/as-ofit was minted under — replaying it under different parameters is a 422, not a silent reset. Of those three, onlyas-ofis carried by the cursor itself:sortandfiltermust be resent verbatim on every page of a walk, or the request falls back to the defaults and the cursor's fingerprint no longer matches. An exhausted cursor returns 200 withnotifications: []andnextCursor: null(unlike offset mode, which 404s on an out-of-range page).
Every response — offset or cursor mode — includes nextCursor, so a client can start with plain page=1 and switch to cursor mode from page 2 onward; nextCursor is null exactly when the walk is exhausted, so there's never a wasted trailing request.
as-of fixes a snapshot: only notifications that existed by that instant (createdAt <= as-of) and whose latest digest was last updated at or before it are returned. It is always echoed back in the response as asOf — pin later requests to that echoed value rather than computing your own, to avoid clock skew between client and server. Note updatedAt is deliberately not bounded by as-of: it's bumped by status changes and votes, including the user's own triage actions, and bounding it would make a row the user just acted on disappear from their own view. A notification whose digest activity moved it outside the snapshot is never re-shown on a later page of the same walk — recover it with a separate query filtering on latestDigestUpdatedAt gt as-of.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
401Missing, expired or invalid access token.
403The access token does not carry the scope this operation requires.
404Not found. On list endpoints a 404 whose body has total: 0 means nothing matched; any other 404 is a real error, such as an unknown ID.
422Invalid query parameters or path. The body names the failing input.
500Unexpected server error. Retry with exponential backoff.
503Service temporarily unavailable. Retry with exponential backoff.

