Stream protocol reference
Generated from the AsyncAPI document (Status302 Stream0.1.0, AsyncAPI 3.0.0). For how to use the protocol, see the stream guide.
Realtime protocol shared by the Status302 web app and client integrations. One WebSocket connection carries many topic subscriptions. Replayable topics carry a per-topic monotonically increasing seq; clients resume with since after reconnecting. When the requested since is older than the replay window the server answers resync with the REST snapshot to reload from. A topic's seq can start over (the server lost its counters); the server then sends resync (reason gap) on the affected subscriptions and continues from the new seq, so clients forget the last seq they kept for a topic on every resync.
ping is answered with heartbeat echoing its id. Subscribing to a topic again replaces its filter. Close codes are listed in x-close-codes; payloads and filters per topic: https://status302.com/docs/stream/.
Encoding: by default every message is a JSON text frame. With ?encoding=msgpack on the upgrade request every server message arrives as one binary MessagePack frame (JSON objects become maps with the same keys in the same order, integers the smallest fitting int, other numbers float64); client messages stay JSON text. Any other encoding value is refused with HTTP 400 before the upgrade.
Firehose filters: Enterprise API keys may subscribe to sales and onsales unfiltered (the whole market). Elite API keys must narrow them to a bounded part of the market, otherwise subscribe is answered forbidden_topic: sales needs country, region, segment, eventIds or listId; onsales needs country, region, segment or attractionIds. scope, source, minPrice and confidence do not count (a few connections with one scope each would rebuild the whole firehose). Signed-in app sessions are not limited.
Servers
| Server | URL | Authentication |
|---|---|---|
| production | wss://api.status302.com/v1/stream | apiKey or ticket |
| development | ws://localhost:8080/v1/stream | As production |
Authentication
apiKey: Authorization header
Bearer tx_live_<keyId>_<secret> on the upgrade request (server-side clients). The key needs the stream scope and a plan with API access (Pro+; the sales/onsales firehoses need Elite+, filtered on Elite and unfiltered on Enterprise). Each topic also needs one scope of its REST equivalent, otherwise subscribe is answered forbidden_topic naming the missing scope: event.{id}.kpis, event.{id}.listings, catalog.rows and catalog.movers need market:read; sales and event.{id}.sales need sales:read; event.{id}.primary needs market:read (seat ids and prices, like its REST snapshot); event.{id}.map needs maps:read or market:read; onsales needs catalog:read; alerts needs alerts:write. Each connection holds one of the org's stream connection slots (plan quota; refused with 4429) and at most the plan's subscriptions per connection. Revoking the key, or the end of its rotation grace or expiry, closes its connections with 4401; changing its scopes closes them with 4409.
ticket: ticket query parameter
Single-use ticket (60 s) from POST /v1/stream/ticket, for browsers; issued to a session or to an API key with the stream scope (the connection then acts as that key, topic scopes included). A user holds at most 20 open connections and a session at most 10 (across every server; 4429 beyond); API keys count against their org's quota instead.
Client messages
JSON text frames you send. Each request carries an id that the reply echoes.
subscribe
{"op":"subscribe","id":"r1","topic":"event.4102.sales"}| Field | Type | Required | Description |
|---|---|---|---|
op | "subscribe" | yes | |
id | string | yes | Client request id echoed in the reply. |
topic | Topic | yes | |
since | integer | no | Replay everything after this seq (replayable topics only). |
filter | object | no | Topic-specific filter (per topic: https://status302.com/docs/stream/). |
unsubscribe
{"op":"unsubscribe","id":"r1","topic":"event.4102.sales"}| Field | Type | Required | Description |
|---|---|---|---|
op | "unsubscribe" | yes | |
id | string | yes | |
topic | Topic | yes |
ping
{"op":"ping","id":"r1"}| Field | Type | Required | Description |
|---|---|---|---|
op | "ping" | yes | |
id | string | yes |
Server messages
JSON text frames the server sends, distinguished by type.
subscribed
{"type":"subscribed","id":"r1","topic":"event.4102.sales","seq":48231}| Field | Type | Required | Description |
|---|---|---|---|
type | "subscribed" | yes | |
id | string | yes | |
topic | Topic | yes | |
seq | integer | yes | Current head seq of the topic. |
snapshot | string | no | REST path returning the full current state. |
data
{"type":"data","topic":"event.4102.sales","seq":48231,"ts":"2026-10-28T18:04:11.204Z","data":{}}| Field | Type | Required | Description |
|---|---|---|---|
type | "data" | yes | |
topic | Topic | yes | |
seq | integer | yes | |
ts | string, date-time | yes | |
data | object | yes |
resync
{"type":"resync","topic":"event.4102.sales","reason":"gap","snapshot":"<snapshot>"}| Field | Type | Required | Description |
|---|---|---|---|
type | "resync" | yes | |
topic | Topic | yes | |
reason | "gap" | "backpressure" | yes | |
snapshot | string | yes |
error
{"type":"error","code":"bad_request","message":"<message>"}| Field | Type | Required | Description |
|---|---|---|---|
type | "error" | yes | |
id | string | no | |
code | "bad_request" | "unknown_topic" | "forbidden_topic" | "subscription_limit" | "rate_limited" | "unavailable" | yes | unknown_topic: not a topic, or an event topic whose event id does not exist. forbidden_topic: the plan, or the API key's scopes, do not allow the topic. unavailable: the topic could not be read right now (Redis); retry the subscribe. |
message | string | yes |
heartbeat
{"type":"heartbeat","ts":"2026-10-28T18:04:11.204Z"}| Field | Type | Required | Description |
|---|---|---|---|
type | "heartbeat" | yes | |
id | string | no | The ping this answers. |
ts | string, date-time | yes |
Error codes
The code of an error message. The connection stays open; the request it answers had no effect.
bad_requestunknown_topicforbidden_topicsubscription_limitrate_limitedunavailable
unknown_topic: not a topic, or an event topic whose event id does not exist. forbidden_topic: the plan, or the API key's scopes, do not allow the topic. unavailable: the topic could not be read right now (Redis); retry the subscribe.
Topics
One of: event.{id}.kpis, event.{id}.sales, event.{id}.primary, event.{id}.listings, event.{id}.map, sales, onsales, alerts, catalog.movers (ranking changes of GET /v1/movers; filter window, direction, scope, cohort; coalesced, at most one message per ranking every 5 s), catalog.rows (app only). event.{id}.map is coalesced (pub/sub, latest state; since is ignored, clients reload GET /v1/events/{id}/map/overlay on subscribe and on resync). Each message is one poll's overlay patch: {eventId, ts, seatmapHash, reload, scopes: {<scope>: {asOf, revision?, sections: [{key, index, tickets, floorMinor, medianMinor, currency}], set?: [placeIndex], clear?: [placeIndex]}}}. Section entries carry the section's new values in full (tickets 0: emptied); set/clear are the places that opened or closed on the primary / tm_resale bitset; reload: true means refetch the overlay (pricing, manifest or a large change). Scopes the plan cannot see are dropped, and plans without map prices get no prices.
Valid topic names match ^(event\.[1-9][0-9]*\.(kpis|sales|primary|listings|map)|sales|onsales|catalog\.rows|catalog\.movers|alerts)$.
Close codes
| Code | Name | Meaning | Reconnect? |
|---|---|---|---|
1001 | going_away | Idle timeout (no client message or pong for 60 s; the server sends heartbeat and pings every 20 s), or a failed write. | Yes, with backoff; resume with since |
1009 | message_too_big | A client message exceeded 64 KiB. | Yes, with backoff; resume with since |
1012 | service_restart | The server is restarting; reconnect and resume with since. | Yes, with backoff; resume with since |
4008 | slow_consumer | The connection's send buffer overflowed; reconnect and resume with since. | Yes, with backoff; resume with since |
4401 | unauthorized | No credentials, ticket invalid or already used, session or API key revoked, key expired or past its rotation grace. Get new credentials before reconnecting. | No, not with the same credentials |
4403 | forbidden | The plan does not allow streaming, or the API key lacks the stream scope. | No, not with the same credentials |
4409 | reconnect | Role, active org, plan or API key scopes changed; fetch a new ticket if you use one, reconnect and resume with since. | Yes, with backoff; resume with since |
4429 | too_many_connections | The org's stream connection quota is used up (API keys), or the user or session already holds its maximum of open connections (signed-in clients; 20 per user and 10 per session by default); close another connection or retry later. | Yes, with backoff; resume with since |
© 2026 status403 Sp. z o.o.Aleja Solidarności 68/121, 00-240 Warsaw, PolandKRS 0001269943NIP 5253108931Share capital PLN 5,000.00
Registry court: District Court for the Capital City of Warsaw, 12th Commercial Division

