---
source_url: https://www.pubnub.com/docs/presence/occupancy
title: Channel occupancy
updated_at: 2026-09-30T07:20:08.000Z
---

# Channel occupancy

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

Occupancy is the number of clients currently subscribed to a [channel](https://www.pubnub.com/docs/architecture/core-concepts.md#channel). [Presence](https://www.pubnub.com/docs/presence/overview.md) reports it two ways: on demand, by calling `Here Now`, and continuously, through the `occupancy` field every [presence event](https://www.pubnub.com/docs/presence/presence-events.md) carries. This page explains:

* what a `Here Now` response contains beyond the raw count
* why that response is briefly cached, and why count-only mode keeps it flat regardless of how large the channel gets
* why the member list is capped and paginated while the occupancy count itself never is
* what changes, and what doesn't, once a busy channel switches to interval mode

An untracked channel returns the same `occupancy: 0` and empty occupant list as an empty channel, so a zero `Here Now` result is not proof that the channel has no subscribers. Check your [Presence Management](https://www.pubnub.com/docs/presence/overview.md) rules before relying on it.

This page doesn't cover the `Here Now` or `Where Now` method syntax. For more information, refer to [Presence](https://www.pubnub.com/docs/presence/overview.md), [Get subscribed channels for a user](https://www.pubnub.com/docs/presence/get-subscribed-channels-for-user.md), and [Get online users in a channel](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md).

## What a Here Now response contains

Call `Here Now` on a channel and PubNub answers with three things:

* the total `occupancy`
* the [User ID](https://www.pubnub.com/docs/architecture/core-concepts.md#user-id) of every occupant
* if set, each occupant's [presence state](https://www.pubnub.com/docs/presence/set-and-get-presence-state.md).

`Here Now` is the fetch counterpart to presence events. Use it once to seed a screen, such as an online-friends list, then switch to events to keep that screen current. Refer to [Presence](https://www.pubnub.com/docs/presence/overview.md) for that pattern and to [Get online users in a channel](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md) for the call itself.

Ask for less and the response shrinks accordingly. The following illustrates a count-only response:

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

That shape stays the same whether the channel has 3 occupants or 3,000. Only the `occupancy` number changes. `occupants` stays empty because count-only mode asked for a number, not a roster. Refer to [Get online users in a channel](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md) for the option that turns count-only mode on and for the full response with occupants and state included.

## Count-only mode keeps the response flat

Returning the full roster costs more the busier a channel gets. PubNub has to list out every occupant and, if you asked for it, every occupant's state.

Count-only mode skips that step, so its response size doesn't grow with occupancy. Reach for it whenever your application only needs the number, such as an "N people online" badge that never lists who they are. Reach for the full response instead when you display or act on individual occupants.

## Here Now is a point-in-time snapshot

`Here Now` returns the occupancy at the moment the server handles the request. The count is accurate at that moment, but a client that calls it in a tight loop pays for each call without getting live tracking.

Use [presence events](https://www.pubnub.com/docs/presence/presence-events.md) to track occupancy as it changes, and call `Here Now` only when you need a confirmed snapshot (such as right after reconnecting).

## Member lists paginate, but occupancy count doesn't

A single `Here Now` call returns up to 1,000 occupants per channel, and you paginate past that with `offset`. That cap applies to the occupant list only. The `occupancy` number in the same response is always the true, uncapped total.

A channel with 5,000 subscribers reports `occupancy: 5000` on every call, even though a single call's `occupants` array holds only the first page of their User IDs.

Page through the rest with repeated calls at increasing `offset` values. Refer to [Get online users in a channel](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md) for the parameter.

## Wildcards require a channel group

`Here Now` takes a channel name, a list of channel names, or a [channel group](https://www.pubnub.com/docs/architecture/core-concepts.md#channel). It doesn't accept a wildcard pattern such as `chats.*`. Wildcard matching is a subscribe-time concept, based on whatever channels currently carry traffic, and `Here Now` needs a fixed target to query.

If your subscribers use a wildcard pattern, put the same channels in a channel group and query the group instead. Refer to [Channels and channel naming](https://www.pubnub.com/docs/pub-sub/subscribe/channels.md#a-convention-decides-what-you-can-address-later) for how one naming convention feeds both a wildcard pattern and a channel group.

## Occupancy on a channel in announce vs interval mode

Presence events run in one of two modes: announce and interval. A channel's occupancy is what decides which.

Below the Announce Max threshold, a channel emits individual `join`, `leave`, and `timeout` events. At or above it, the channel emits periodic `interval` events instead, while `state-change` stays individual in both modes. The Announce Max threshold is configured in [Presence Management](https://www.pubnub.com/docs/presence/overview.md). For the full mechanics, refer to [Presence events](https://www.pubnub.com/docs/presence/presence-events.md#channel-occupancy-decides-announce-mode-or-interval-mode).

`Here Now` doesn't change with it. It keeps returning the same occupancy, occupants, and state for a channel in interval mode as for one in announce mode. The `occupancy` field on the `interval` event stays accurate too. What stops at the threshold is the per-client event stream, not the count.

That makes `Here Now` more useful on a busy channel. Presence webhooks stop firing once a channel passes that threshold. A server that tracked occupancy through webhooks loses that signal exactly when the channel gets busy enough to need it. Refer to [API limits](https://www.pubnub.com/docs/architecture/limits.md#presence) for the threshold's default and maximum. Polling `Here Now`, or subscribing to the channel's `interval` events directly, is what still works above it.

An `interval` event's optional delta arrays can also get dropped, if including them would push the event past the platform's message size limit. When that happens, the event carries `hereNowRefresh: true` instead of the deltas. Treat that flag as a prompt to call `Here Now`, since the roster you'd have gotten from the deltas didn't arrive. Refer to [Presence events](https://www.pubnub.com/docs/presence/presence-events.md#presence-deltas-add-who-changed-to-an-interval-event) for the full payload.

## Next steps

* [Presence](https://www.pubnub.com/docs/presence/overview.md). How presence data is enabled and delivered, and how occupancy relates to presence state and events.
* [Presence events](https://www.pubnub.com/docs/presence/presence-events.md). Event subtypes, announce and interval modes, deltas, and heartbeat configuration.
* [Get online users in a channel](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md). Call Here Now to list current subscribers and their state.
* [Get subscribed channels for a user](https://www.pubnub.com/docs/presence/get-subscribed-channels-for-user.md). Call Where Now for a specific User ID.
* [Set and get presence state](https://www.pubnub.com/docs/presence/set-and-get-presence-state.md). The custom state a Here Now response can include per occupant.
* [Presence Management](https://www.pubnub.com/docs/presence/overview.md). Configure which channels track presence, and the announce max threshold.
* [API limits](https://www.pubnub.com/docs/architecture/limits.md#presence). Here Now cache time, occupant cap, announce max, and heartbeat limits.

Last updated at: 2026-09-30T07:20:08.000Z