Skip to main content
GET
Pull entitled events

Authorizations

Authorization
string
header
required

A bearer JWT issued by plugin-auth (lib-auth). The tenant identity is resolved from the validated token claims; the /v1 surface never reads a tenant from the body, path, or query. Machine callers obtain a token via the plugin-auth client-credentials flow. The /admin surface authorizes against an operator scope and carries no tenant context.

Query Parameters

subscription_id
string<uuid>
required

The pull subscription to read. Resolved through an existence gate then a kind gate: an absent, cross-tenant, or non-pull id all return a uniform 404 not_found (no existence or kind oracle).

after
integer<int64>

Explicit keyset cursor (replay). When present it overrides the persisted cursor for the read; absent it, the read resumes from the persisted acknowledged seq (0 = from the beginning). A malformed value is ignored and folds to the persisted cursor.

limit
integer

Page size, clamped to the range 1–500, defaulting to 100.

Response

A page of events in ascending seq order.

events
object[]
required

A page of events in ascending seq order.

next_cursor
integer<int64> | null
required

The maximum seq in the page when it filled exactly to limit (a possible next page); null on a short or final page. This diverges deliberately from the subscriptions list cursor (which is a DESC-by-id string with an empty-string sentinel).

Example:

42