# Usage Plans & Rate Limits

## Overview

This page describes the rate limits, burst allowances, and quotas for our API across different usage plans. These limits apply to the Core, Conversation Hub, and Knowledge Hub APIs. API version availability varies by service — some services support both v3 and v4, while newer services are available in v4 only. The rate limit tables below indicate the version(s) applicable to each service.

**Crucially, rate limits are applied on a per-endpoint basis.**

* **Independent Buckets:** Each individual endpoint path (e.g., `GET /folders`, `POST /folders`, `GET /articles`) has its own dedicated rate limit bucket.
* **Isolation:** If one endpoint hits its limit and returns a `429 Too Many Requests` error, other endpoints in that collection **are not affected**. You can continue calling other APIs without interruption.


## Understanding Rate Limits

- **Rate Limit**: The maximum number of API calls allowed per second for a specific endpoint.
- **Burst Limit**: The maximum number of requests that can be made in a short spike for a specific endpoint.
- **Per-Endpoint Isolation**: Each endpoint's traffic is tracked independently. Throttling on one resource does not trigger throttling on others.
- **Scope**: Rate limits are applied per tenant. All requests made under the same tenant share the same limit buckets for each endpoint, regardless of which application or integration is making the call.


## How to Read the Limit Tables

For each API collection listed below:

1. **Standard Limits**: Every endpoint in that collection (unless listed as "Special") has the rate and burst limit defined in the **Rate Limit** and **Burst Limit** columns. For example, if the limit is 0.5 req/sec, `Endpoint A` and `Endpoint B` each get 0.5 independently.
2. **Special Endpoints**: This column lists specific paths that have their own unique limits. These "Special" limits override the standard limits for that specific path only.


## Conversation Hub APIs

### Conversation Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | `/conversations/messages` (POST): 1 req/sec`/conversations/{id}` (GET): 1 req/sec`/assets` (POST): 1 req/sec`/assets/{id}` (GET): 1 req/sec |
| v3 | **Enterprise** | 1 req/sec | `/conversations/messages` (POST): 5 req/sec`/conversations/{id}` (GET): 5 req/sec`/assets` (POST): 5 req/sec`/assets/{id}` (GET): 5 req/sec |


### Message Router

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | — |
| v3 | **Enterprise** | 0.5 req/sec | `/entrypoint/{id}/agentavailability` (GET): 1 req/sec`/entrypoint/{id}/capacity` (GET): 1 req/sec`/entrypoint/{id}/checkeligibility` (GET): 1 req/sec`/entrypoint/{id}/chatallowed` (GET): 1 req/sec`/entrypoint/{id}/livesessionstatus` (GET): 1 req/sec |


### Notification Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | `/messages` (POST): 1 req/sec`/assets` (POST): 1 req/sec |
| v3 | **Enterprise** | 1 req/sec | `/messages` (POST): 5 req/sec`/assets` (POST): 5 req/sec |


### Secure Messaging Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | — |
| v3 | **Enterprise** | 1 req/sec | — |


## Core Hub APIs

### AI Services

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | `/instantanswers/suggestions` (GET): 10 req/sec |
| v3 | **Basic** | 0.3 req/sec | `/instantanswers/suggestions` (GET): 20 req/sec |
| v3 | **Enterprise** | 1 req/sec | `/instantanswers/generative` (GET): 30 req/sec`/instantanswers/extractive` (GET): 30 req/sec`/instantanswers/suggestions` (GET): 40 req/sec |
| v4 | **Developer** | 30 req/sec | — |
| v4 | **Basic** | 30 req/sec | — |
| v4 | **Enterprise** | 30 req/sec | — |


### Auth Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 1 req/sec | — |
| v3 | **Basic** | 10 req/sec | — |
| v3 | **Enterprise** | 60 req/sec | — |


### Case Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | — |
| v3 | **Enterprise** | 1 req/sec | — |


### Customer Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | — |
| v3 | **Enterprise** | 1 req/sec | — |


### Department Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.16 req/sec | — |
| v3 | **Enterprise** | 0.5 req/sec | — |
| v4 | **Developer** | 0.16 req/sec | — |
| v4 | **Basic** | 0.16 req/sec | — |
| v4 | **Enterprise** | 0.5 req/sec | — |


### Events Channel

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.16 req/sec | — |
| v3 | **Enterprise** | 0.5 req/sec | — |


### File Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | — |
| v3 | **Enterprise** | 0.5 req/sec | — |


### Info Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.16 req/sec | — |
| v3 | **Enterprise** | 0.5 req/sec | — |
| v4 | **Developer** | 0.16 req/sec | — |
| v4 | **Basic** | 0.16 req/sec | — |
| v4 | **Enterprise** | 0.5 req/sec | — |


### Integration Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v4 | **Developer** | 0.16 req/sec | — |
| v4 | **Basic** | 0.5 req/sec | — |
| v4 | **Enterprise** | 1 req/sec | — |


### Micro Services Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.5 req/sec | — |
| v3 | **Enterprise** | 1 req/sec | — |


### Personalization Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v4 | **Developer** | 0.16 req/sec | — |
| v4 | **Basic** | 0.5 req/sec | — |
| v4 | **Enterprise** | 1 req/sec | — |


### User Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 1 req/sec | `/user` (POST): 0.16 req/sec`/user` (PATCH): 0.16 req/sec`/user/{id}` (DELETE): 0.16 req/sec`/user/ext-id/{id}` (DELETE): 0.16 req/sec |
| v3 | **Basic** | 10 req/sec | `/user` (POST): 0.16 req/sec`/user` (PATCH): 0.16 req/sec`/user/{id}` (DELETE): 0.16 req/sec`/user/ext-id/{id}` (DELETE): 0.16 req/sec |
| v3 | **Enterprise** | 60 req/sec | `/user` (POST): 0.5 req/sec`/user` (PATCH): 0.5 req/sec`/user/{id}` (DELETE): 0.5 req/sec`/user/ext-id/{id}` (DELETE): 0.5 req/sec |


### Work Assignment Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 0.16 req/sec | — |
| v3 | **Basic** | 0.16 req/sec | — |
| v3 | **Enterprise** | 0.5 req/sec | — |


## Knowledge Hub APIs

### Content Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v4 | **Developer** | 1 req/sec | `/import/content` (POST): 0.02 req/sec`/import/content/validate` (POST): 0.02 req/sec |
| v4 | **Basic** | 10 req/sec | `/import/content` (POST): 0.08 req/sec`/import/content/validate` (POST): 0.08 req/sec |
| v4 | **Enterprise** | 60 req/sec | `/import/content` (POST): 0.17 req/sec`/import/content/validate` (POST): 0.17 req/sec |


### Event Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v4 | **Developer** | 0.5 req/sec | — |
| v4 | **Basic** | 0.5 req/sec | — |
| v4 | **Enterprise** | 0.5 req/sec | — |


### Portal Manager

| Ver | Plan | Rate Limit | Special Endpoints |
|  --- | --- | --- | --- |
| v3 | **Developer** | 1 req/sec | `/portals/{portalID}/search/typeahead` (GET): 10 req/sec |
| v3 | **Basic** | 10 req/sec | `/portals/{portalID}/search/typeahead` (GET): 20 req/sec |
| v3 | **Enterprise** | 60 req/sec | `/portals/{portalID}/search/typeahead` (GET): 60 req/sec |
| v4 | **Developer** | 1 req/sec | — |
| v4 | **Basic** | 10 req/sec | — |
| v4 | **Enterprise** | 60 req/sec | — |


## How Burst Limits Work

Our system utilizes a **Token Bucket** algorithm to manage traffic. **Every unique endpoint path has its own independent bucket.**

1. **Individual Buckets**: Your plan provides a separate "bucket" for every endpoint.
2. **Refill Rate**: Each bucket refills at the "Rate Limit" frequency (e.g., if the limit is 0.5 req/sec, the bucket refills at a rate of 1 token every 2 seconds).
3. **Burst Capacity**: The bucket can hold extra tokens up to your "Burst Limit," allowing for sudden spikes in traffic.
4. **Independent Consumption**: Calling `Endpoint A` only consumes tokens from `Bucket A`. `Bucket B` remains full and ready for use.


### Example of Endpoint Isolation

**Plan: Basic Plan — Case Manager** (Rate Limit: 0.5 req/sec | Burst: 10)

* **Scenario**: You send a high volume of requests to `GET /cases` and receive a `429 Too Many Requests` error.
* **Result**: While `GET /cases` is throttled, you can still immediately call `GET /cases/{id}` or `POST /cases`. Because those are different endpoint paths, their rate limit buckets are completely independent and will still be available.


## Handling Rate Limit Errors

When an individual endpoint exceeds its rate limit, the API returns:

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
```

```json
{
  "code": "429-001",
  "developerMessage": "Too many requests."
}
```

### Best Practices

1. **Per-Endpoint Backoff**: If you receive a 429, only pause or "back off" requests to that specific endpoint. You do not need to stop traffic to other endpoints in the same API.
2. **Implement Exponential Backoff**: We recommend an exponential backoff strategy (e.g., wait 1s, then 2s, then 4s) for the specific resource being throttled.
3. **Client-Side Throttling**: We recommend implementing your own client-side rate limiting to match the values in the tables above.
4. **Cache When Possible**: Reduce the frequency of calls to static resources (like Folder or Department lists) by caching responses to avoid hitting per-endpoint limits.