Get a list of notifications

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 by updatedAt descending unless sort is given. Simple, but page=N can 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's nextCursor): 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. currentPage is not meaningful in this mode (always 1); cursor and page cannot both be set (422). A cursor is scoped to the sort/filter/as-of it was minted under — replaying it under different parameters is a 422, not a silent reset. Of those three, only as-of is carried by the cursor itself: sort and filter must 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 with notifications: [] and nextCursor: 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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
integer
integer
1 to 1000
Defaults to 10
string

JSON-encoded filter, URL-encoded in the query string. A single clause: {"key":"name","operator":"ilike","type":"string","value":"acme"}. type is required (string, int, float, boolean, datetime or null). Operators: eq, not-eq, lt, lte, gt, gte, in, not-in, like, not-like, ilike, not-ilike, between, not-between. like and ilike add the % wildcards themselves, so pass the bare value. Groups: {"operator":"and","clauses":[...]} (or or), nested up to 3 levels. A filter on an unknown key returns the empty-list 404.

string
enum
Allowed:
string

JSON-encoded array of sort keys, URL-encoded, for example [{"key":"name","desc":false},{"key":"createdAt","desc":true}]. An unknown key returns 422.

date-time
string
length between 1 and 4096
Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

401

Missing, expired or invalid access token.

403

The access token does not carry the scope this operation requires.

404

Not 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.

422

Invalid query parameters or path. The body names the failing input.

500

Unexpected server error. Retry with exponential backoff.

503

Service temporarily unavailable. Retry with exponential backoff.

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
text/plain