---
source_url: https://www.pubnub.com/docs/general/presence/presence-occupancy
title: Presence Occupancy
updated_at: 2026-08-07T10:23:24.000Z
---

# Presence Occupancy

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

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](https://www.pubnub.com/docs/general/presence/presence-events.md) to track changes in real time.

:::note 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](https://www.pubnub.com/docs/general/setup/users-and-devices.md#set-the-user-id).
:::

## 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](https://www.pubnub.com/docs/general/presence/presence-state.md), if set

```javascript
const response = await pubnub.hereNow({
  channels: ['my_channel'],
  includeState: true,
});
// response.channels['my_channel'].occupancy  → subscriber count
// response.channels['my_channel'].occupants  → [{ uuid, state }, ...]
```

:::note 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`:

```javascript
const response = await pubnub.hereNow({
  channels: ['my_channel'],
  includeUUIDs: false,
});
```

Example response:

```json
{
  "totalChannels": 1,
  "totalOccupancy": 3,
  "channels": {
    "my_channel": {
      "name": "my_channel",
      "occupancy": 3,
      "occupants": []
    }
  }
}
```

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:

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

// Next 100 occupants
await 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.

###### SDK API references for Here Now

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](https://www.pubnub.com/docs/sdks/javascript/api-reference/presence.md#here-now), [Swift](https://www.pubnub.com/docs/sdks/swift/api-reference/presence.md#here-now), [Kotlin](https://www.pubnub.com/docs/sdks/kotlin/api-reference/presence.md#here-now), or [Python](https://www.pubnub.com/docs/sdks/python/api-reference/presence.md#here-now).

## Occupancy on large channels

On channels with many subscribers, individual [presence events](https://www.pubnub.com/docs/general/presence/presence-events.md) (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](https://www.pubnub.com/docs/general/presence/presence-events.md#interval-mode) for full details on interval mode and delta payloads.

:::warning 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](https://www.pubnub.com/docs/general/setup/limits.md#presence).

## Terms in this document

* **Channel** - A pathway for sending and receiving messages between devices, created automatically when you first use it, that can handle any number of users and messages for different communication needs, like 1-1 text chats, group conversations, and other data streaming.
* **Channel pattern** - A way to group and analyze channel data to track performance metrics like message counts and user engagement over time with PubNub Insights.
* **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username.
* **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.

Last updated at: 2026-08-07T10:23:24.000Z