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

> ## Agent Instructions
> Base URL: https://api.eventory.ai. Send your API key in the apikey header. Market Data and Live Availability calls cost credits, pings included; GET /usage is free, so use it to test a key. Costs per endpoint: https://eventory.ai/docs/credits-and-access.md

# Real-time ticket notifications (WebSocket)

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

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

> [!NOTE]
>
> Access to the Notifications API is **not included in any API plan**. It is granted
> separately, to a limited number of partners. Contact Eventory to ask about access.

For keys that are granted it, the Notifications API deducts no credits, and neither do
the watchlist calls that control it.

## How it fits together

**1. 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`.

**2. 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.

**3. 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.

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

The server applies exactly two filters before forwarding a notification:

1. **Event membership.** The event must be on your watchlist under an active item;
   items with `task_active: false` get no notifications. An item matches in any id
   format the watchlist accepts, such as an AXS numeric id or event URL, and the
   message's `event_id` is not always the value you saved.
2. **Change type.** The notification's `changes` must contain the `change_type` set
   on that item (default `stock_increase`). When several active items watch the same
   event, one of them matching is enough.

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.

## Delivery

Delivery is at-most-once. Nothing is queued for you while you are disconnected and
nothing is replayed when you reconnect. The server restarts every few hours, so plan
for short gaps. See [Connecting](/docs/stream/connecting.md#lifecycle).

## Duplicate suppression

After a notification is delivered to your account, another one for the same event with
the same total `stock` and the same change types, each with the same section names in
`changes`, is suppressed for **15 minutes**. Prices are not compared, so another price
move of the same type on the same sections at the same total stock is not delivered
within that window. Suppression is per account, so all connections from the same
account share it.

## Multiple connections

You may open several sockets per key. Each gets its own queue, but because they share
duplicate suppression, each notification usually reaches only one of them. Use extra
connections for failover, not to fan notifications out to several consumers; if every
consumer needs every message, fan out from a single connection yourself.

> [card] [Connecting](/docs/stream/connecting.md)
>
> Handshake, errors, reconnection strategy, and a working client.

> [card] [Message format](/docs/stream/messages.md)
>
> The notification envelope and the section shapes.


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