API limits
PubNub applies two kinds of limit to every keyset and API described on this page:
- a soft limit, a recommended operating range you can exceed without an error
- a hard limit, an enforced ceiling that PubNub rejects, throttles, or truncates once you cross it
Each section states both, and what happens if you hit the hard one. If PubNub detects abnormal or abusive traffic on a keyset, it may also apply a temporary rate limit to the affected APIs. PubNub Support contacts you if that happens.
This page covers technical limits. For the features and allowances that change with your Free, Starter, or Pro plan, see Plan comparison.
Keysets
Every limit below applies per keyset.
PubNub keyset limits by account tier:
| Account tier | Soft limit | Hard limit |
|---|---|---|
| Free | 3 keysets | 3 keysets |
| Starter | Unlimited | Unlimited |
| Pro | Unlimited | Unlimited |
A Free tier account that reaches the hard limit must delete an existing keyset before it can create another.
Publish
Limits on sending a message to a channel.
| Function | Limit | Notes |
|---|---|---|
| Publish rate | There is no hard publish rate limit for a keyset in good standing. As a best practice, keep publish rates at 10 to 15 messages per second per channel. Faster rates are possible, but a slow subscriber can fall behind the connection's message buffer. | Refer to Subscribe limits for the buffer a slow subscriber falls behind. |
| Publishers per channel or keyset | PubNub places no limit on how many publishers a channel or keyset has. | |
| Message size | The standard message payload size limit is 32 KiB. This includes the channel name and any metadata. | Enforced as the length of the GET request, including HTTP headers and URI-encoding overhead. Exceeding it returns HTTP 400. To raise it, contact support@pubnub.com. |
| Channel name length | Channel names cannot exceed 92 UTF-8 characters. | |
| User ID length | A User ID cannot exceed 92 UTF-8 characters. |
Subscribe
Limits on receiving messages, including the per-connection buffer that protects a client against short disconnects.
| Function | Limit | Notes |
|---|---|---|
| Subscribe rate | No limit | Use HTTP streaming rather than polling for the highest throughput. |
| Channels per client | PubNub places no limit on the number of channels a keyset or a client uses. | |
| Subscribers per channel or keyset | The number of subscribers on a PubNub channel is unlimited. | |
| Message buffer cache | The subscriber message buffer queues messages for a reconnecting client. It holds 100 messages for up to 16 minutes by default, and discards the oldest first (FIFO) when a burst exceeds that size. Larger buffers, for example 300 or 500 messages, can be provisioned per keyset by PubNub Support. | For recovery beyond the buffer window, enable Message Persistence. |
| Catch-up on reconnect | The size of the buffer cache | |
| Channel name length | Same limit as Publish. | |
| Sockets per client instance | Each PubNub client instance uses two TCP sockets: one for subscribe requests and one for all non-subscribe operations. | PubNub places no limit on how many client instances you create, though the device or browser may cap concurrent TCP connections. |
| Multiplexing (without Stream Controller) | 10 to 50 channels recommended | No per-SDK limit is enforced. PubNub advertises 100 channels as the practical ceiling. There's no server-side count limit, only the URI length limit under Publish. |
| Wildcard subscribe | Up to 3 dot-separated levels, for example a.* or a.b.* | Not supported on channel groups. |
| Channel groups | Each PubNub keyset supports up to 10 channel groups. Each group holds up to 1,000 channels by default. Paid plans can raise the cap to 2,000 channels per group. | Channel group name length: 92 characters. Exceeding the per-client group count returns HTTP 400 (Maximum channel registry count exceeded). |
File sharing
Limits on files sent to a channel through Files.
| Function | Limit | Notes |
|---|---|---|
| File size | 5 MB | To raise it, contact support@pubnub.com. |
| File retention | File retention is 1 or 7 days on the Free plan, 30 days on Starter, and Unlimited on Pro. | Set it per keyset in the Admin Portal. |
| Files per list call | A single list-files call returns up to 100 files for a channel. |
Presence
Limits on tracking who's connected to a channel through Presence.
| Function | Limit | Notes |
|---|---|---|
presenceTimeout default | PubNub SDKs set presenceTimeout to 300 seconds by default, which is how long PubNub waits without a heartbeat before marking a client offline. | Also called presenceHeartbeatValue or durationUntilTimeout in some SDKs. A client that times out emits timeout. |
heartbeatInterval default | Explicit presence heartbeats are off by default in PubNub SDKs, because heartbeatInterval defaults to 0. | Implicit heartbeats from subscribe calls still keep an actively subscribing client marked present. Also called presenceHeartbeatInterval in some SDKs. |
| SDK heartbeat and heartbeat interval | Recommended: 1-minute heartbeat, 29-second heartbeat interval | These are client-side SDK settings, separate from the keyset Interval below. Older 3.x SDKs enforce a minimum of heartbeat 10, heartbeat interval 4. SDKs on the current 4.x line have no minimum. |
Presence Interval range | The keyset's Presence Interval setting, the cadence of interval events on a channel in interval mode, ranges from 10 to 3,600 seconds. | |
| Presence announce max per channel | Default 20, from 0 to 100 | The occupancy threshold above which a channel switches from individual join/leave/timeout events to interval mode. PubNub can raise the maximum on request. Contact support@pubnub.com. |
| Webhook retries | 4 attempts, 5-second timeout each | Your endpoint must return HTTP 200. After the last retry, an undelivered webhook is dropped. PubNub sends no webhook at all for a channel that has already reached its presence announce max. |
Here Now occupants per call | A single Here Now call returns up to 1,000 occupants per channel, and you paginate past that with offset. | The occupancy count itself isn't subject to this cap. It always reflects the true subscriber total. |
Message Persistence
Limits on storing and retrieving message history through Message Persistence.
PubNub Message Persistence limits:
| Setting | Limit | Notes |
|---|---|---|
| Data retention | Message Persistence retention is 1 or 7 days on the Free plan, 30 days, 3 months, or 6 months on Starter, and 1 year or Unlimited on Pro. | Free tier keysets are capped at 7 days. Set the retention period per keyset in the Admin Portal. |
| Messages per history call | A single history call returns up to 100 messages for one channel, or up to 25 messages per channel across as many as 500 channels. | Page backward with the timetokens each response returns. |
| Channels per message-count call | A single messageCounts call covers up to 100 channels. | Applies to the call that returns unread message counts for multiple channels in one request. |
Message Actions
Limits on attaching a Message Action, such as a reaction, a receipt, or a custom annotation, to a message.
| Item | Limit | Notes |
|---|---|---|
| Request size | Same limit as Publish. | A message action is sent as a standard PubNub API request, so the publish request-body limit applies. |
type and value fields | No dedicated limit | Bounded only by the overall request size. |
App Context
Limits on storing user, channel, and membership metadata through App Context.
| Item | Limit | Notes |
|---|---|---|
| Metadata record size | One user, channel, or membership metadata record can hold up to 32 KiB, counting every field including custom. | This is a storage limit on the record, separate from the publish message-size limit. |
| User and channel metadata records | 1 million each (recommended) | Recommended maximum per keyset when using the App Context API. |
| Memberships and channel members | Platform limits apply: up to 50,000 memberships per user and up to 5,000 members per channel. | |
| Members or memberships per write | 20 per request | Maximum number added or removed in a single App Context call. |
For the maximum length of individual fields such as name, externalId, email, type, and status, see the REST API reference for setting user metadata, channel metadata, a user's channel memberships, and a channel's members. If a custom field holds an integer, such as a timetoken, send it as a string when the value can exceed 9007199254740991, the largest integer JSON can represent without losing precision.
For the maximum length of each field on a user, channel, or membership record, refer to App Context API limits.
Mobile push
Limits on sending push notifications through Mobile push notifications.
| Item | Limit |
|---|---|
| Push credentials per keyset | 1 APNs certificate and 1 FCM key |
| Push notification payload size | 2 KB for APNs, 4 KB for FCM |
Access Manager
Limits on issuing permission tokens through Access Manager.
| Item | Limit | Notes |
|---|---|---|
| Tokens | Unlimited | |
| Channels per grant | 200 | |
| Token TTL | An Access Manager token's ttl ranges from 1 minute to 43,200 minutes (30 days). | Every Access Manager token requires a ttl in minutes, and there is no default. |
| Token size | Access Manager grantToken() requests over 32 KiB return HTTP 414 (URI Too Long). | Prefer RE2 patterns over long resource lists, and keep resource names short. |
| Token revocation | Token revocation is available only when the keyset's token TTL is 43,200 minutes (30 days) or less. | Token revocation is disabled by default. |
| Grant-to-use latency | No enforced limit | Leave at least 1 second between a server-to-server grant and its first use. When a server grants a token for a client to use, wait for the grant call to return before handing the token to the client. |
Functions
Limits on execution, outbound calls, and KV Store usage in Functions.
| Item | Limit |
|---|---|
| Modules per keyset | 10 |
xhr requests per execution | 5 |
| Vault reads per execution | 10 |
| PubNub API, publish, and KV Store calls per execution | 10 each |
| Outbound call rate | 100 requests/sec total, across xhr and Vault requests |
| Loop iterations per execution | 100,000 |
| Execution recursion depth | 3 hops, whether chaining Function types or re-triggering the same one |
| CPU wall time | 10 seconds per execution |
KV Store keys per getKeys call | 100 |
| KV Store key size | A KV store key can be up to 1,000 characters. |
| KV Store value size | A KV store value can be up to 32,000 characters. |
| KV Store TTL | A KV store entry lives for 1 day by default, and a per-entry TTL can range from 1 minute up to 1 year. |
| Interval Function schedule | 1 hour maximum between executions |
| Console debug and error messages | A Function replica publishes up to 250 console log lines over its lifetime, not per execution, and output stops silently once a replica reaches that budget. |
To request a higher limit, contact support@pubnub.com.
Events & Actions
Limits on forwarding PubNub events to third-party systems through Events & Actions. Ingestion, listener, and action limits scale with your account tier.
PubNub Events & Actions limits by tier:
| Item | Free | Intro | Tier 1 | Tier 2 | Tier 3 | Tier 4 | Tier 5 | Tier 6 |
|---|---|---|---|---|---|---|---|---|
| Events ingested per month | 10K | 2M | 4M | 25M | 66M | 200M | 500M | Unlimited |
| Listeners | 1 | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited |
| Actions per listener | 1 | 3 | 3 | 3 | 3 | 3 | Unlimited | Unlimited |
Your keyset's tier is set by your PubNub plan.
Service Integrations and API keys
Limits on the API keys you generate for a Service Integration to call PubNub's management APIs.
| Item | Limit |
|---|---|
| API keys per Service Integration | 3 |
| API key TTL | 1 year maximum |
| Service Integrations per account | Unlimited |