Rate limits

Stream powers video, chat and activity feeds for a billion end users. That being said, Stream does have rate limits to protect your applications (making many API requests can trigger client-side events causing degraded app performance) and Stream’s infrastructure (using more capacity than is provisioned for your plan).

Every Application has rate limits applied based on a combination of API endpoint and platform: these limits are set on a 1-minute time window. For example, creating a call has a different limit than querying calls. Likewise, different platforms such as iOS, Android or your server-side infrastructure have independent counters for each API endpoint’s rate limit.

Types of rate limits

There are two kinds of rate limits:

User Rate Limits: Apply to each user and platform combination and help to prevent a single user from consuming your Application rate limits.
App rate limits: App rate limits are calculated per endpoint and platform combination for your application.

User Rate Limits

To avoid individual users consuming your entire quota, every single user is limited to at most 60 requests per minute (per API endpoint and platform). When the limit is exceeded, requests from that user and platform will be rejected.

App Rate Limits

Stream supports four different platforms via our official SDKs:

Server: SDKs that execute on the server including Node, Python, Ruby, Go, C#, PHP, and Java.
Android: SDKs that execute on an Android device including Kotlin, Java, Flutter, and React Native for Android clients.
iOS: SDKs that execute on an iOS device including Swift, Flutter, and React Native for iOS clients.
Web: SDKs that execute in a browser including React, Angular, or vanilla JavaScript clients.

Rate limits quotas are not shared across different platforms. This way if by accident a server-side script hits a rate limit, you will not have any impact on your mobile and web applications. When the limit is hit, all calls from the same app, platform, and endpoint will result in an error with a 429 HTTP status code.

App rate limits are administered both per minute and per second. The per-second limit is equal to the per-minute limit divided by 30 to allow for bursts.

What To Do When You’ve Hit a Rate Limit

You should always review responses from Stream to watch for error conditions. If you receive 429 status, this means your API request was rate-limited and you will need to retry. We recommend implementing an exponential back-off retry mechanism.

Here are a few things to keep in mind to avoid rate limits on server-side:

Slow down your scripts: This is the most common cause of rate limits. You’re running a cronjob or script that runs many API calls in succession. Adding a small timeout in between API calls typically solves the issue.
Use batch endpoints: Batch update endpoints exist for many operations. So instead of doing 100 calls to update 1 user each, call the batch endpoint for updating many users.
Query only when needed: Sometimes apps will call a query endpoint to see if an entity exists before creating it. Many of Stream’s endpoints have an upsert behaviour, so this isn’t necessary in most cases.
If rate limits are still a problem, Stream can set higher limits for certain pricing plans:

For Standard plans, Stream may also raise rate limits in certain instances, an integration review is required to ensure your integration is making optimal use of the default rate limits before any increase will be applied.
For Enterprise plans, Stream will review your architecture, and set higher rate limits for your production application.

Rate limit headers

Header	Description
X-RateLimit-Limit	the total limit allowed for the resource requested (i.e. 5000)
X-RateLimit-Remaining	the remaining limit (i.e. 4999)
X-RateLimit-Reset	when the current limit will reset (Unix timestamp)

This is how you can access rate limit information on server-side SDKs:

const response = client.....;
const rateLimit = response.metadata.rateLimit;

// the total limit allowed for the resource requested
console.log(rateLimit.rateLimit);
// the remaining limit
console.log(rateLimit.rateLimitRemaining);
// when the current limit will reset - Date
console.log(rateLimit.rateLimitReset);

// or

try {
    client....
} catch (error) {
    const rateLimit = response.metadata.rateLimit;
    if (error.metadata.responseCode === 429) {
        // Wait until rate limit resets and then retry
    }
}

Inspecting rate limits

Stream offers the ability to inspect an App’s current rate limit quotas and usage in your App’s dashboard. Alternatively you can also retrieve the API Limits for your application using the API directly.

// 1. Get Rate limits, server-side platform
limits = await client.getRateLimits({ server_side: true });

// 2. Get Rate limits, all platforms
limits = await client.getRateLimits();

// 3. Get Rate limits, iOS and Android
limits = await client.getRateLimits({ ios: true, android: true });

// 4. Get Rate limits for specific endpoints
limits = await client.getRateLimits({
  endpoints: 'QueryCalls,GetOrCreateCall',
});

# 1. Get Rate limits, server-side platform
curl -X GET "https://video.stream-io-api.com/api/v2/rate_limits?api_key=${API_KEY}&server_side=true" \
    -H "Authorization: ${TOKEN}" \
    -H "stream-auth-type: jwt"

# 2. Get Rate limits, all platforms
curl -X GET https://video.stream-io-api.com/api/v2/rate_limits?api_key=${API_KEY} \
    -H "Authorization: ${TOKEN}" \
    -H "stream-auth-type: jwt"

# 3. Get Rate limits, iOS and Android
curl -X GET "https://video.stream-io-api.com/api/v2/rate_limits?api_key=${API_KEY}&ios=true&android=true" \
    -H "Authorization: ${TOKEN}" \
    -H "stream-auth-type: jwt"

# 4. Get Rate limits for specific endpoints
PAYLOAD='QueryCalls,GetOrCreateCall';
ENCODED_PAYLOAD=$(echo ${PAYLOAD} | perl -MURI::Escape -lne 'print uri_escape($_)')

curl -X GET "https://video.stream-io-api.com/api/v2/rate_limits?api_key=${API_KEY}&endpoints=${ENCODED_PAYLOAD}" \
    -H "Authorization: ${TOKEN}" \
    -H "stream-auth-type: jwt"

Networking and Firewall

Overview