> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull events with a cursor

> Read your Streaming Hub events page by page from a pull subscription, where each read acknowledges the page it returns.

Read your events on your own schedule, with no endpoint to expose.

## Participants

***

* **Your institution.** Your system calls the Streaming Hub API with an Access Manager token.
* **Streaming Hub.** The Lerian platform service that keeps your events in arrival order and returns them page by page. Lerian sets it up for your institution.
* **Lerian product.** The product that publishes the business event, for example Midaz.

## Diagram

***

![Pull events with a cursor](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-pull-events-with-a-cursor.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=97cc633b3c21b888b7ad71e8872d2559)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Streaming Hub | Lerian API | [`POST /v1/subscriptions`](https://docs.lerian.studio/en/reference/platform/streaming-hub/create-subscription) | Create the subscription with a `name`, `sink_kind` `pull` and the `event_types` you want. Send no endpoint. Send a unique `X-Idempotency` header. |
| 2 | Streaming Hub | Your institution | Response | | The subscription is `active` at once. A pull subscription needs no ping and has no signing secret. |
| 3 | Lerian product | Streaming Hub | Event | | The product publishes a business event. |
| 4 | Streaming Hub | Streaming Hub | Internal step | | Streaming Hub keeps the event and gives it a sequence number, `seq`, in arrival order. |
| 5 | Your institution | Streaming Hub | Lerian API | [`GET /v1/events`](https://docs.lerian.studio/en/reference/platform/streaming-hub/pull-events) | Read a page with `subscription_id`. The optional `limit` goes from 1 to 500, and the default is 100. |
| 6 | Streaming Hub | Streaming Hub | Internal step | | Streaming Hub moves the cursor of the subscription to the highest `seq` on the page. The read is the acknowledgment. |
| 7 | Streaming Hub | Your institution | Response | | The page has the events in `seq` order, each with its `ceId`, and `next_cursor`. |
| 8 | Your institution | Your institution | Internal step | | Process the events. Ignore a `ceId` that you already processed. |
| 9 | Your institution | Streaming Hub | Lerian API | [`GET /v1/events`](https://docs.lerian.studio/en/reference/platform/streaming-hub/pull-events) | Read the next page. Send `next_cursor` as `after`, or send no `after` to continue from the cursor. |
| 10 | Streaming Hub | Your institution | Response | | When the page has fewer events than `limit`, `next_cursor` is `null`. |

## How you know it finished

***

A read returns `next_cursor` `null`.

* **Your system stops after a read.** The cursor already moved past that page. Read again with `after` set to the last `seq` that you processed. That read does not move the cursor back.
* **The read is refused for rate.** The read answers `429` `rate_limited`. Wait the `Retry-After` seconds, then read again.

## Related

***

* [Receive events on a webhook](https://docs.lerian.studio/en/diagrams/platform-services/receive-events-on-a-webhook.md)
* [Consuming events](https://docs.lerian.studio/en/platform/streaming-hub/consuming-events.md)
* [Managing subscriptions](https://docs.lerian.studio/en/platform/streaming-hub/managing-subscriptions.md)
* [Streaming Hub errors](https://docs.lerian.studio/en/reference/platform/streaming-hub/streaming-hub-error-list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.