Presence Occupancy

Channel occupancy tells you how many clients are currently subscribed to a channel. Use the Here Now API to query it on demand, and presence events to track changes in real time.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Query channel occupancy

Here Now returns three things for a channel:

• Occupancy — the total count of active subscribers
• Member list — the User IDs of each subscriber
• State — each subscriber's custom presence state, if set

1const response = await pubnub.hereNow({
2  channels: ['my_channel'],
3  includeState: true,
4});
5// response.channels['my_channel'].occupancy  → subscriber count
6// response.channels['my_channel'].occupants  → [{ uuid, state }, ...]

Response cache

Here Now responses are cached for 3 seconds.

Count-only mode

To retrieve only the occupancy count without the member list, set includeUUIDs: false or limit: 0:

1const response = await pubnub.hereNow({
2  channels: ['my_channel'],
3  includeUUIDs: false,
4});

Example response:

1{
2  "totalChannels": 1,
3  "totalOccupancy": 3,
4  "channels": {
5    "my_channel": {
6      "name": "my_channel",
7      "occupancy": 3,
8      "occupants": []
9    }
10  }
11}

The response size stays constant regardless of how many clients are on the channel, because no member list is returned. This makes count-only mode efficient for high-occupancy channels.

Member list limits

Here Now returns up to 1,000 occupants per channel per call. Use offset to page through larger member lists:

1// First 100 occupants (offset defaults to 0, no need to pass it)
2await pubnub.hereNow({ channels: ['my_channel'], limit: 100 });
3

4// Next 100 occupants
5await pubnub.hereNow({ channels: ['my_channel'], limit: 100, offset: 100 });

The occupancy count is not subject to this limit — it always reflects the true total number of subscribers, regardless of how many members are returned in a single call.

Parameter names and method signatures vary by SDK. For full parameter details, return types, and additional examples for your language, refer to the Here Now section of your SDK's API reference — for example, JavaScript, Swift, Kotlin, or Python.

SDK API references for Here Now

Occupancy on large channels

On channels with many subscribers, individual presence events (join, leave, timeout) can generate significant message traffic. PubNub handles this with interval mode: when a channel's occupancy exceeds the Announce Max threshold, PubNub stops sending individual join/leave/timeout events and instead sends a periodic interval event containing the channel's total occupancy.

Occupancy tracking continues to work normally in interval mode — Here Now and the occupancy field in interval events both reflect the true subscriber count.

If the delta data in an interval event exceeds the 32 KiB publish limit, PubNub trims it and sets hereNowRefresh: true in the payload. This signals your client to call Here Now for the current member list. See Presence Events for full details on interval mode and delta payloads.

Presence webhooks above Announce Max

PubNub does not send presence webhook requests for channels that have exceeded the Announce Max threshold. If you rely on webhooks to track occupancy changes, use the Here Now API to poll or subscribe to interval events directly on high-occupancy channels.

Occupancy limits

The following limits apply to occupancy-related operations:

Limit	Value
Subscribers per channel	Unlimited
Occupants returned per Here Now call	1,000 (paginate with offset)
Interval delta payload	32 KiB, then hereNowRefresh: true
Presence webhooks above Announce Max	Not sent

For the full presence limits reference, see API Limits.