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

# Stream overview

> A WebSocket that pushes a notification whenever an event on your watchlist changes.

The real-time stream is a push API. You open one WebSocket and the server sends a
JSON message every time an event on your [watchlist](/reference/introduction#watchlist)
has a relevant change: stock appears, a price moves, a new section opens. There is no
polling endpoint; everything arrives over the socket.

The stream is **free**: it deducts no credits, and neither do the watchlist calls that
control it.

## How it fits together

<Steps>
  <Step title="Put events on your watchlist">
    Each watchlist item names a platform, an event id, a region, and optionally a
    `change_type` and filters. Use `POST /watchlist`.
  </Step>

  <Step title="Open the socket">
    Connect to `wss://api.eventory.ai/eventory/notifications/subscribe` with your key
    in the `apikey` header. The account must have at least one watchlist item.
  </Step>

  <Step title="Receive notifications">
    Each message is one JSON frame describing the change and the current state of the
    event's sections. Watchlist changes propagate to the open socket within 60 seconds,
    no reconnect needed.
  </Step>
</Steps>

## What the server filters, and what it does not

The server applies exactly two filters before forwarding a notification:

1. **Event membership.** The notification's `event_id` must be on your watchlist.
2. **Change type.** The notification's `changes` must contain the `change_type` set
   on that watchlist item (default `stock_increase`).

Every other watchlist field is **not** enforced server-side. If you set any of
`min_price_filter`, `max_price_filter`, `stock_threshold_filter`, `seat_quantity`,
`section`, `keywords`, the ticket-type booleans, `date_filter`, `row_filter` or
`muted_until`, your client must apply them to the messages it receives.

## Duplicate suppression

Identical notifications are suppressed for **15 minutes**. If nothing meaningful has
changed about an offer in that window you will not see it again; after 15 minutes the
next matching change is delivered. Deduplication is keyed on the notification content
plus your account, so multiple connections from the same account share it.

## Multiple connections

You may open several sockets per key. Each gets its own queue, which is useful for
running a cluster. Every open socket counts separately against the connection rate
limit when it reconnects, so keep the number small.

<CardGroup cols={2}>
  <Card title="Connecting" href="/stream/connecting" icon="plug">
    Handshake, errors, reconnection strategy, and a working client.
  </Card>

  <Card title="Message format" href="/stream/messages" icon="envelope">
    The notification envelope and the two section shapes.
  </Card>
</CardGroup>