Pull entitled events

Fetches a page of a pull subscription’s entitled events in arrival-order seq. The read doubles as the acknowledgment (cursor-as-ack): after a successful fetch the newest seq the read examined is persisted as the subscription’s cursor, monotonically: the last event of a full page, and the tenant’s newest seq on a short or empty page. An explicit after cursor overrides the persisted cursor for the read; a forward seek advances the durable cursor past the unread gap (the skipped range is not re-delivered — caller-owns-the-gap), while a backward seek never rewinds it. The read is rate-limited per tenant. Events are at-least-once; deduplicate on ceId.

GET /v1/events

Pull entitled events

cURL

curl --request GET \
  --url https://streaming-hub.sandbox.lerian.net/v1/events \
  --header 'Authorization: Bearer <token>'

200

{
  "events": [
    {
      "seq": 42,
      "ceId": "0192f1a0-0000-7000-8000-0000000000ce",
      "eventType": "orders.created",
      "schemaVersion": "1.0.0",
      "receivedAt": "2026-06-06T12:00:00Z",
      "payload": {
        "order_id": "abc",
        "amount": 42
      }
    }
  ],
  "next_cursor": 42,
  "retention_loss": {
    "from_seq": 4810,
    "to_seq": 5122,
    "detected_at": "2026-11-01T03:00:12Z"
  }
}

Authorizations

Authorization · string · header · required

A bearer JWT issued by Access Manager. The /v1 surface never reads a tenant from the body, path, or query. Machine callers obtain a token with the Access Manager 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 or negative value is ignored and folds to the persisted cursor.

limit · integer

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

Response

200

application/json

A page of events in ascending seq order.

events · object[] · required

A page of events in ascending seq order.

Show child attributes

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

retention_loss · object | null · required

The events that retention removed before this subscription read them, or null. Every read that starts below to_seq reports it. A read that ends at or past to_seq (a short page) moves the cursor past it, so a client that resumes from the cursor sees null next. After a full page that ends below to_seq, or for a client that tracks its own after, it repeats until a read starts at or above to_seq.

Show child attributes