Occupancy

Occupancy provides high level metrics about the clients attached to a channel. This includes the number of connections currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel.

Occupancy metrics

The following are the metric categories that occupancy reports:

Metric	Description
connections	The number of connections
publishers	The number of connections that are authorized to publish
subscribers	The number of connections that are authorized to subscribe to messages
presenceSubscribers	The number of connections that are authorized to subscribe to presence messages
presenceConnections	The number of connections that are authorized to enter members into the presence channel
presenceMembers	The number of members currently entered into the presence channel

Realtime occupancy updates

Subscribe to occupancy events in realtime using the occupancy channel option:

Query occupancy via REST

You can query occupancy for a single channel using the REST API:

Enumerate channels with occupancy

List all active channels and their occupancy:

Occupancy payload structure

When subscribing to [meta]occupancy events, the message structure is:

Use cases

Display active users

Monitor capacity

Track engagement

Occupancy vs Presence

Feature	Occupancy	Presence
Purpose	High-level channel metrics	Individual member tracking
Identifies users	No	Yes (by clientId)
Member data	No	Yes (custom status)
Overhead	Minimal	Higher (per-member events)
Best for	Showing “X users online”	Avatar stacks, member lists

Use occupancy when you only need counts. Use presence when you need to know who is online.

Next steps

• Learn about presence for detailed member tracking
• Explore channel metadata
• Understand channel options