API usage restrictions

This page provides a brief overview of the restrictions of the Agora Signaling SDK, including API call limit, string size, encoding, and more.

API call limit

Unless otherwise specified below, limit the API call frequency by a single client to 20 calls per second. If the number of calls per second exceeds 20, some calls are ignored by the SDK. If you need to call more APIs per second, contact rtm@agora.io.

General

Item	Soft limit	Hard limit	Comments
Number of projects in an account	1000	N/A	To change the limit, contact rtm@agora.io.
Number of client instances	1	1	Attempts to create multiple instances fail.
Number of message channels per app ID	Unlimited	N/A	Channel resources are public, users can take them as needed.
Number of stream channels per app ID	Unlimited	N/A	Channel resources are public, users can take them as needed.
User ID length	64 ASCII characters	64 ASCII characters	Exceeding the soft limit produces an error.

Message channel

Item	Soft limit	Hard limit	Comments
Number of messages per second in a channel	30 messages/sec	60 messages/sec	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Number of subscribers per channel	Unlimited	N/A
Number of publishers per channel	Unlimited	N/A
Number of subscribed channels per client	50	N/A	Exceeding the soft limit produces an error.
Message packet size	32 KB	32 KB	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Channel name length	64 ASCII characters	64 ASCII characters	Exceeding the soft limit produces an error.
Custom message type length	32 ASCII characters	32 ASCII characters	Exceeding the soft limit produces an error.

Stream channel

Item	Soft limit	Hard limit	Comments
Number of created channels per client	Unlimited	N/A
Number of joined channels per client	100	N/A	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Number of users per channel	1000	N/A	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Number of topics per channel	Unlimited	N/A
Channel name length	64 ASCII characters	64 ASCII characters	Exceeding the soft limit produces an error.

Topic

Item	Soft limit	Hard limit	Comments
Number of topics joined by a client in a channel	8	8	Exceeding the soft limit produces an error.
Number of messages published by a client in a topic per second	120 messages/sec	200 messages/sec	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Number of topics subscribed to by a client in a channel	50	50	Exceeding the soft limit produces an error.
Number of users subscribed to a topic by a client	64	64	A single client can subscribe up to 64 user IDs to a single topic. Exceeding the soft limit produces an error.
Number of publishers in a topic	Unlimited	N/A
Topic name length	8 ASCII characters	8 ASCII characters	The topic name length will be extended to 64 ASCII characters in future releases.
Message packet size	32 KB	32 KB	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Custom message type length	32 ASCII characters	32 ASCII characters	Exceeding the soft limit produces an error.

Presence

Item	Soft limit	Hard limit	Comments
Presence timeout	10 seconds - 300 seconds. Defaults to 300 seconds.	N/A	When the set timeout value is exceeded, the SDK matches the closest boundary value. For example, if you set presence timeout to 400 seconds, the actual application time is 300 seconds. To change the limit, contact rtm@agora.io.
Number of temporary user state key/value pairs	32 pairs	32 pairs	Exceeding the soft limit produces an error.
Number of temporary user states cached before joining the channel	100	100	Exceeding the soft limit produces an error.

Storage

Item	Soft limit	Hard limit	Comments
Metadata item key length	32 ASCII characters	N/A
Number of metadata sets per user or channel	1	1	Each channel and each user can only have one set of channel or user metadata, respectively.
Number of items per channel metadata or user metadata set	Unlimited	N/A
Storage space per channel or user metadata set	64KB	N/A	To change the limit, contact rtm@agora.io.
Storage space per metadata item	64KB	N/A	To change the limit, contact rtm@agora.io.
Channel metadata API call frequency by a single client	10 times/sec	20 times/sec	To change the limit, contact rtm@agora.io.
User metadata API call frequency by a single client	10 times/sec	20 times/sec	To change the limit, contact rtm@agora.io.
Number of channel metadata sets per app ID	1 million	N/A
Number of user metadata sets per app ID	1 million	N/A	To change the limit, contact rtm@agora.io.

Lock

Item	Soft limit	Hard limit	Comments
Number of locks per channel	32	N/A	To change the limit, contact rtm@agora.io.
Number of locked locks per client	Unlimited	N/A
Lock TTL (Time to live)	10 seconds - 300 seconds	10 seconds - 300 seconds	When a user leaves a channel or disconnects, the lock held by that user is automatically released after the set time. When the set value is exceeded, the SDK matches the closest boundary value. For example, if you set lock TTL to 400 seconds, the actual application time is 300 seconds.
Lock length	64 ASCII characters	64 ASCII characters	Exceeding the soft limit produces an error.
Number of locks per app ID	1 million	N/A	Exceeding the soft limit produces an error. To change the limit, contact rtm@agora.io.
Lock acquisition API call frequency	10 times/sec	N/A

String size

The maximum size of the response in a call invitation is 8 KB.

Unicode support

Supports channel and peer-to-peer messages, invitation content, and invitation response in UTF-8 only.

Call limit

The call limit is for one RtmClient instance. If an operation corresponds to multiple methods, the number of the method calls of an operation equals the sum of the method calls of all corresponding methods in a specific time frame.

You can increase the call limit of an API by creating multiple RtmClient instances.

Operation	Method	Call limit
Log in the Signaling	login	2 calls per second
Retrieve member count of specified channel(s)	getChannelMemberCount	1 call per second
Join a different channel each time	join	50 calls every 3 seconds
Join the same channel each time	join	2 calls every 5 seconds
Send messages	sendMessageToPeer sendMessageToPeer sendMessage sendMessage	180 calls every three seconds
Retrieve a member list of the channel	getMembers	5 calls every 2 seconds
Renew the token	RtmClient.renewToken	2 calls per second
Query the online status of the specified users	queryPeersOnlineStatus	10 calls every 5 seconds
Set user attributes	setLocalUserAttributes addOrUpdateLocalUserAttributes deleteLocalUserAttributesByKeys clearLocalUserAttributes	10 calls every 5 seconds
Get user attributes	getUserAttributes getUserAttributesByKeys	40 calls every 5 seconds
Set channel attributes	setChannelAttributes addOrUpdateChannelAttributes deleteChannelAttributesByKeys clearChannelAttributes	10 calls every 5 seconds
Get channel attributes	getChannelAttributes getChannelAttributesByKeys	10 calls every 5 seconds
Subscribes to the online status of the specified user(s)	subscribePeersOnlineStatus	10 calls every 5 seconds
Unsubscribes from the online status of the specified user(s)	unsubscribePeersOnlineStatus	10 calls every 5 seconds
Gets a list of the peers, to whose specific status you have subscribed.	queryPeersBySubscriptionOption	10 calls every 5 seconds

String size

The maximum size of a peer-to-peer or channel message is 32 KB. See RtmMessage.setText.
The maximum size of the content in a call invitation is 8 KB. See LocalInvitation.setContent.
The maximum size of the response in a call invitation is 8 KB. See RemoteInvitation.setResponse.

Encoding

Channel and peer-to-peer messages, invitation content, and invitation response must be in UTF-8 format.
The filePath parameter of the following methods must be in UTF-8 format:

Miscellaneous

Notifications of a member joining or leaving the channel are automatically disabled when the number of channel members exceeds 512.
The current version supports querying the online status of up to 256 users.
You can subscribe to the online status of up to 512 users in one method call, and you can subscribe to the online status of up to 512 users.
Attribute settings in one user attribute operation must not exceed 16 KB in size. Attribute settings in one channel attribute operation must not exceed 32 KB in size. Each attribute (key/value pair) must not exceed 8 KB in size. You must not set over 32 key/value pairs for one attribute operation.
Each file or image you upload to the Agora server stays for seven days. The corresponding media ID also stays valid for seven days.
Each file or image to upload must not exceed 30 MB in size.
Each client instance can only support up to nine upload and download processes at the same time.