API: Rate and Bandwidth Limitations

Limits

In general, we operate the API in good faith that you will play nicely with reasonable requests to the Initial State Events API. Here are a few guidelines/limits when streaming data into the Initial State Events API:

Individual and Business Tiers:
  • 3 API calls per second per account
  • Measured in 10 second intervals to allow bursting of up to 30 API calls in one second
  • 200 KB max payload per API call

Rate Limit Headers

The API will respond with your current rate limit within the response headers of every call. Here are the headers and their definitions:

  • X-RateLimit-Limit - This shows what your current number of requests per 10 second interval is. This remains constant while not changing your plan.
  • X-RateLimit-Remaining - This shows how many requests are remaining until you hit your limit. This number re-ups to the X-RateLimit-Limit every 10 seconds.
  • X-RateLimit-Reset - This shows a Unix epoch in seconds to indicate a time in the future when the X-RateLimit-Remaining will reset
  • Retry-After - This header only comes back on 429 responses indicating that the request has been denied because of the exhausted rate limit. You can use this header to set your wait time, in seconds, so that your next request will be successful.

Tips

Buffer Events

Each API call can contain multiple events and each event can contain it's own timestamp (ISO-8601 or Unix Epoch). We have multiple support articles on how to send multiple events in a single call:
  • Using the API to send multiple events in one call when using the API directly
  • Using the Python SDK also buffers automatically, the calling application has control over buffer size and flush rate. 
For example, if you send 20 events per API call and make 3 calls per second, you would be logging 60 events every second at an average rate of 1 event per 16.67 ms.  Each of the 60 events can have a unique timestamp giving you fine control over the timing resolution.

If you exceed the bandwidth limitations, the Events API will return 429 response (too many requests) and data will not be stored. If you continually exceed the bandwidth limitations more than the average user, your account may be suspended to protect the performance of other users.

Don't Over Buffer

While the API does allow event buffering and buffering is highly encouraged. It's general best practice to find the sweet spot between buffer size and call frequency. Currently it's discouraged from sending really spiky event payloads. For instance, it's better to send 10 events in a single post per second than to send 600 events every minute.

Feedback and Knowledge Base