> ## Documentation Index > Fetch the complete documentation index at: https://docs-dev.auth0-mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. > Pull events from Auth0 on your own schedule using the Server-Sent Events (SSE) based Events API. # Consume Events with the Events API The Events API provides a pull-based alternative to Event Streams. Instead of Auth0 pushing events to a destination, your application opens a long-lived connection to `GET /api/v2/events` and receives events as a Server-Sent Events (SSE) stream. You control when to connect, how to resume after a disconnection, and how fast to consume events. This approach is useful when you need to: * Process events at your own pace without standing up a webhook endpoint. * Replay events from a specific point in time for backfill or recovery. * Integrate with systems that prefer polling over push-based delivery. ## How the Events API works When your application connects to the Events API, it receives a stream of SSE messages. Each message includes an `id` field that acts as an **offset**. If the connection drops, your application reconnects and provides the last offset it received. Auth0 resumes delivery from that point, so no events are lost. The SSE stream includes the following message types: | Message type | Purpose | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `:connected` | Confirms the connection is established. This is an SSE comment, not a data event. | | `retry: ` | Tells the SSE client how long to wait before reconnecting after a disconnect. | | `event: ` (for example, `user.created`) | A real event with full payload in the `data` field. | | `event: offset-only` | A progress marker sent at regular intervals (on heartbeat frequency). Updates the offset without delivering event data. | | `:` followed by text (for example, `: heartbeat`) | A keep-alive comment that prevents proxies and load balancers from closing idle connections. No action required. | | `event: error` | A terminal error. The stream closes after this message. | ### Example SSE stream ```text wrap lines theme={null} :connected retry: 2000 event: user.created id: MTIzNDIzNDEzCg== data: {"offset":"MTIzNDIzNDEzCg==","event":{"id":"evt_abc123","type":"user.created","time":"2025-06-01T12:00:00Z","data":{"object":{"user_id":"auth0|123","email":"jane@example.com"}}}} event: offset-only id: 4LcuTXmVDASuNRQt data: {"offset":"4LcuTXmVDASuNRQt"} : heartbeat event: user.updated id: NTY3ODkwMTIzCg== data: {"offset":"NTY3ODkwMTIzCg==","event":{"id":"evt_def456","type":"user.updated","time":"2025-06-01T12:05:00Z","data":{"object":{"user_id":"auth0|123","email":"jane.doe@example.com"}}}} ``` ## Prerequisites Before you begin, make sure you have: * An Auth0 tenant with Events enabled. The number of Event Stream connections available depends on your plan: | Plan | Connection limit | | ------------ | ---------------- | | Free | 1 | | Self-service | 4 | | Enterprise | 8 | * A Management API access token with the `read:events` scope. To learn more, read [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens). ## Connect to the Events API Open an SSE connection to the events endpoint on your tenant. The following example uses `curl`: ```bash wrap lines theme={null} curl -N --http2 \ -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \ -H "Accept: text/event-stream" \ "https://YOUR_DOMAIN/api/v2/events" ``` ### Query parameters Use query parameters to filter or resume the stream: | Parameter | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | string | An offset returned in a previous `id` field. Delivery resumes after this offset. | | `from_timestamp` | string | An ISO 8601 timestamp. Returns events that occurred at or after this time. Mutually exclusive with `from`. Best used for initial setup or replaying events from a known point in time; for ongoing consumption, prefer resuming with `from` because offsets are more precise. | | `event_type` | string | The event type to include. Repeat the parameter for each type (for example, `event_type=user.created&event_type=user.updated`). | ```bash wrap lines theme={null} curl -N --http2 \ -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \ -H "Accept: text/event-stream" \ "https://YOUR_DOMAIN/api/v2/events?event_type=user.created&event_type=user.updated&from_timestamp=2025-06-01T00:00:00Z" ``` ## Resume after a disconnection SSE connections can drop for many reasons: network issues, token expiration, or server-side connection cycling (Auth0 periodically closes connections for load balancing — typically every few minutes). Standard SSE client libraries handle this transparently by reconnecting and sending the last offset. There are two ways to supply the offset on reconnection: * **`Last-Event-ID` header** — the standard SSE reconnection mechanism. Most SSE client libraries set this header automatically when reconnecting. * **`from` query parameter** — use this when your client does not support the `Last-Event-ID` header. If both are provided, the `Last-Event-ID` header takes precedence. ```bash wrap lines theme={null} curl -N --http2 \ -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \ -H "Accept: text/event-stream" \ -H "Last-Event-ID: MTIzNDIzNDEzCg==" \ "https://YOUR_DOMAIN/api/v2/events" ``` Persist the latest `id` value from every message (including `offset-only` messages) to durable storage. If your application restarts, use the persisted offset to resume delivery from where you left off. ## Handle message types ### Real events Messages where the `event` field matches a known event type (for example, `user.created`) contain the full event payload in the `data` field. Parse the JSON and process the event according to your business logic. ### Offset-only messages Auth0 sends `offset-only` messages at regular intervals (on the heartbeat frequency) to advance your position in the stream. These messages do not contain an event payload. Update your stored offset when you receive them so that a future reconnection does not replay events you have already passed. ### Error messages An `event: error` message signals a terminal issue such as an expired offset or a server-side problem. After receiving this message, the stream closes. Your application should log the error, then reconnect with the appropriate offset or a fresh `from_timestamp`. ### Heartbeats Lines that begin with `:` are SSE comments used as heartbeats. They keep the connection alive through proxies and load balancers. No processing is required. ## Server-side connection cycling Auth0 periodically closes SSE connections for load-balancing purposes (typically every few minutes). This is expected behavior, not an error. Standard SSE client libraries (including the `eventsource` npm package) reconnect automatically using the `Last-Event-ID` header, so your application resumes from the correct offset without losing events. If you build a custom SSE client, make sure it handles connection drops gracefully by persisting the latest offset and reconnecting with it. ## Implement a consumer The following Node.js example demonstrates a minimal Events API consumer that processes events and persists the offset to a file. ```javascript wrap lines theme={null} const EventSource = require("eventsource"); const fs = require("fs"); const OFFSET_FILE = "./offset.txt"; const AUTH0_DOMAIN = "YOUR_DOMAIN"; const TOKEN = "YOUR_MANAGEMENT_API_TOKEN"; function loadOffset() { try { return fs.readFileSync(OFFSET_FILE, "utf8").trim(); } catch { return null; } } function saveOffset(offset) { fs.writeFileSync(OFFSET_FILE, offset); } function connect() { const offset = loadOffset(); const params = new URLSearchParams(); params.append("event_type", "user.created"); params.append("event_type", "user.updated"); params.append("event_type", "user.deleted"); if (offset) { params.append("from", offset); } const url = `https://${AUTH0_DOMAIN}/api/v2/events?${params.toString()}`; const es = new EventSource(url, { headers: { "Authorization": `Bearer ${TOKEN}` } }); // Handle real events for (const type of ["user.created", "user.updated", "user.deleted"]) { es.addEventListener(type, (msg) => { const payload = JSON.parse(msg.data); console.log(`Received ${type}:`, payload.event.id); // Process the event here saveOffset(msg.lastEventId); }); } // Handle offset-only progress markers es.addEventListener("offset-only", (msg) => { saveOffset(msg.lastEventId); }); // Handle terminal errors es.addEventListener("error", (msg) => { if (msg.data) { const errorPayload = JSON.parse(msg.data); console.error("Stream error:", errorPayload.error); } es.close(); // Reconnect after a delay setTimeout(connect, 5000); }); } connect(); ``` The `eventsource` npm package implements the SSE protocol and handles reconnection automatically using the `Last-Event-ID` header. If you use a different SSE library, verify that it supports automatic reconnection and offset forwarding. ## Error responses The Events API returns standard HTTP status codes when the connection cannot be established: | Status code | Meaning | | ----------- | --------------------------------------------------------------------------------------------- | | `200` | Connection established. Events begin streaming. | | `400` | Invalid request. The offset value is malformed or the requested event type is not supported. | | `401` | Missing or invalid access token. | | `403` | The access token does not include the `read:events` scope. | | `410` | The offset has expired. Use a `from_timestamp` value to resume from a specific point in time. | | `429` | Rate limit exceeded. Wait and retry using the interval from the `Retry-After` header. | ## Learn more * [Event Types](/docs/customize/events/event-types) * [Create an Event Stream](/docs/customize/events/create-an-event-stream) * [Events Best Practices](/docs/customize/events/events-best-practices) * [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens)