The Clarabridge Engage API only allows clients to make a limited number of calls in a given hour. This policy affects the APIs in different ways.

Limits for Authenticated Calls and Unauthenticated Calls

The default rate limit for calls to the REST API varies depending on the authorization method being used and whether the method itself requires authentication.

  • Unauthenticated calls are permitted 150 requests per hour. Unauthenticated calls are measured against the public facing IP of the server or device making the request.
  • OAuth calls are permitted 350 requests per hour and are measured against the oauth_token used in the request.

In general, these rate limits are applied to methods that request information, update and/or delete information. To be sure about the exact rate limits, read the information from the API Response's HTTP Headers (see below).
We reserve the right to adjust these rate limits subject to fair use limits.

WARNING The rate limits of tokens from the API Console are lower (20 authenticated calls per hour instead of 350 calls per hour) than the default for other API Clients. Please register your own API Client for production use.

Rate Limit HTTP Headers

For rate limited API calls, extra information is included in the http headers of the response.

X-RateLimit-Limit
How many calls are allowed per timeframe.
X-RateLimit-Time
Timeframe, in seconds.
X-RateLimit-Remaining
How many calls you have left (until X-RateLimit-Reset time) before you will be rate limited.
X-RateLimit-Reset
Unix timestamp when the counter will be reset.

Knowing if you are rate limited

If your application is being rate-limited by the API it will receive HTTP 400 response codes and the content of the response will be an error with value "rate_limit_reached". It is best practice for applications to monitor their current rate limit status and dynamically throttle requests if necessary. (See above.)

Whitelisting

API Rate Limit Whitelisting is not provided. Resourceful use of more efficient requests will allow you to build your integration successfully without requiring whitelisting.

Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don't try to call the API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.

If your site keeps track of many Clarabridge Engage users, consider only requesting data for users who have recently signed into your site.

This page is based on the Rate Limiting guidelines of Twitter.