API usage restrictions

This page describes the limits that apply to Signaling SDK 2.x and its RESTful APIs, what happens when your application exceeds a limit, and how to plan capacity. Use it to:

• Resolve rate-limit errors.
• Fix sending failures caused by oversized messages or parameters.
• Diagnose rising latency or repeated reconnections as a channel grows.
• Estimate peak concurrent users and plan channel message rates before launch.
• Request a higher limit.

How limits workCopy Anchor Link

Each Signaling limit applies at a specific level and has a type that determines what happens when you exceed it.

Limit levelsCopy Anchor Link

Signaling limits apply at four levels. Higher levels limit total volume, and lower levels limit individual objects. A single call can be subject to limits at more than one level.

Limit typesCopy Anchor Link

Each limit has one of the following types:

Account-level limitsCopy Anchor Link

The following limit applies to all projects in your Agora account:

Project-level limits (App ID)Copy Anchor Link

The following limits apply to each project, identified by its App ID:

Estimate PCUCopy Anchor Link

Signaling limits and billing are based on PCU, but application metrics often use daily active users (DAU), room count, or class count. Use the formula that matches your application:

The peak factor scales daily averages to peak periods. A value of 2 to 3 is a common starting point. For a known peak event, such as a sale, a tournament, or the start of a school term, use the expected event peak instead of a daily average.

When you estimate PCU, avoid the following common errors:

• Counting users instead of connections: Each connection counts separately. A user who signs in on a phone and in a browser counts as two PCU.
• Ignoring heartbeatInterval: A longer heartbeat interval delays offline detection, which can increase the reported PCU. The default is 5 seconds, and the range is 5 to 1,800 seconds.

Channel-level limitsCopy Anchor Link

Channel-level limits cover how many users and resources a single channel can hold, and how many messages per second it can handle.

CapacityCopy Anchor Link

The following limits apply to a single channel:

Channel message rate recommendationsCopy Anchor Link

The channel message rate is the total number of messages that all publishers, including clients and RESTful APIs, send to one channel per second. Signaling calculates this rate separately from the client rate limits, so the channel total can exceed the recommendation even when every client stays within its own limit.

The recommended rate depends on the number of concurrent users in the channel. Each additional user increases the fan-out cost of every message, so a larger channel can handle fewer messages per second:

When a channel exceeds the recommended rate, the SDK usually doesn't return an error. Instead, latency can increase, messages can be lost, and users might be unable to send or receive messages or might reconnect repeatedly.

When a channel approaches the recommended rate, do the following:

• Split users across multiple channels, and check each channel against the recommended rates.
• Use stream channels and topics for frequent, small messages. Keep each stream channel under 128 users.
• Aggregate messages on your application server, and send the result using the RESTful API to reduce the upstream message count.
• If you need a higher rate, contact support in advance. Agora can provide a custom increase if it doesn't affect latency or stability.

Client-level limitsCopy Anchor Link

The following limits apply to each Signaling client instance. Signaling counts each client separately.

Rate limitsCopy Anchor Link

Signaling groups client APIs into operation categories, and each category has its own per-second quota. Methods in the same category share a quota, and categories don't affect each other. For example, 15 calls to getOnlineUsers and 15 calls to getChannelMetadata in the same second don't trigger a rate limit because the two methods belong to different categories. However, 25 calls to getOnlineUsers in the same second do trigger a rate limit.

The SDK doesn't run or queue calls that exceed a quota. Instead, it reports a rate-limit error in its error callback. To handle the error, throttle or retry the call in your application. For details, see Handle exceeded limits.

Operations with dedicated quotasCopy Anchor Link

The following operations have their own quotas:

All other operationsCopy Anchor Link

Each row in the following table is an independent category with a quota of 20 calls per second. Methods in the same row share that quota.

Connections and instancesCopy Anchor Link

The following limits apply to client instances and to the channels and topics that each client uses:

Message specificationsCopy Anchor Link

The following limits apply to messages and to the names and queries that messages use:

Presence specificationsCopy Anchor Link

The following limits apply to Presence:

Storage specificationsCopy Anchor Link

The following limits apply to channel and user metadata:

Metadata stays stored after you write it. Destroying a channel or logging out a user doesn't delete it. Delete metadata explicitly when you no longer need it.

Lock specificationsCopy Anchor Link

The following limits apply to locks:

RESTful API limitsCopy Anchor Link

The following limits apply to the Signaling RESTful APIs:

Plan channel message ratesCopy Anchor Link

To estimate the message rate of a channel, use the following formula:

channel message rate ≈ active publishers in the channel × messages sent per publisher per second

Compare the result with the channel message rate recommendations. Estimate the number of concurrent users and the message rate separately: the number of concurrent users determines the fan-out cost, and therefore the recommended rate that applies.

The following table shows example scenarios. When you plan, replace the example values with measurements from your application.

Keep the following points in mind when you estimate:

• The activity ratio and per-user frequency affect the result most. Replace the example values with measurements from your application.
• Each row describes one channel. Check each channel separately against the recommendations. The project-level total upstream rate of 100,000 messages per second still includes every channel. See Project-level limits.

Frequently asked questionsCopy Anchor Link

The following questions cover common misunderstandings about Signaling limits.

Handle exceeded limitsCopy Anchor Link

How you detect and handle an exceeded limit depends on the type of limit:

The following pseudocode shows one retry pattern for a rate-limit error. For the callback that each platform SDK uses, see the API reference for your platform.

send(msg):
  result = rtm.publish(channel, msg)
  if result.error == RATE_LIMITED:
    delay = min(baseDelay * 2^attempt, maxDelay)  // 100 ms to 2 s
    wait(delay)
    attempt += 1
    if attempt < maxAttempts:
      send(msg)
    else:
      report("publish dropped after retries")
  else:
    attempt = 0

Retries alone aren't enough to stay within your quotas. For more reliable results, use a token bucket for each operation category. For example, use a bucket of 60 calls per second for sending messages and a bucket of 20 calls per second for each other category.

Request higher limitsCopy Anchor Link

You can request an increase, or discuss capacity planning, for the following limits. Contact support@agora.io or your Agora technical support contact, and include your App ID, expected scale, and launch date.