API: Rate & 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:

Student Tier

• 60 Events API calls per minute per account.
• Measured in 10 second intervals to allow bursting of up to 10 Events API calls in one second.
• 30 Read API calls per minute per account.
• Each call can be up to 10 events (data points) per API call.
• 3 million total incoming data points per month per account.
• If the amount of incoming streaming data sent to your Initial State account through the Events API within a month exceeds 3 million events, your API access will be throttled until the next month.

Individual Tier

• 180 Events API calls per minute per account.
• Measured in 10 second intervals to allow bursting of up to 30 API calls in one second.
• 30 Read API calls per minute per account.
• Each call can be up to 10 events (data points) per API call.
• 3 million total incoming data points per month per account.
• If the amount of incoming streaming data sent to your Initial State account through the Events API within a billable month exceeds 3 million events, your API access will be throttled until the next billable month.

Enterprise Tier

• 360 Events API calls per minute per account by default. You can request to increase this by contacting us at support@initialstate.com
• Measured in 10 second intervals to allow bursting of up to 60 API calls in one second.
• 30 Read API calls per minute per account.
• Each call can be up to 10 events (data points) per API call.
• Pay-as-you-go pricing for incoming data points. $2/mo per 1 million incoming data points. Stream in as many data points as you need.

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.