Understand limits on Knewton API request rates
In this section:
Knewton enforces a set of rate limits, i.e. limits on frequency and volume of interactions with the Knewton API. These limits ensure that no one user or partner can impact the availability of the system for other users on our multi-tenant platform. Rate limits are designed to accommodate use-cases of most applications. Partners should contact their Knewton representative if their applications are frequently rate-limited by Knewton’s APIs.
Knewton enforces rate limits in a few ways:
When an application exceeds one of these rate limits, Knewton will respond to a request with an HTTP error response containing:
X-Knewton-Rate-Exceeded header that indicates which type of rate limit was exceeded {"message": "Too many requests."}
IP Address-based rate limiting is enforced when an incoming request has yet to be authenticated (i.e. a request is made to retrieve access or refresh tokens) or if an incoming request has failed authentication (i.e. a request is made with incorrect or expired tokens).
If the client exceeds this rate, Knewton will attempt to queue the next request. This will result in a delay in
processing the request. Knewton will include an X-Knewton-Rate-Delay header in the response that will contain the time
of the delay in milliseconds. For instance, if the response contains X-Knewton-Rate-Delay: 100, it means that the
response was delayed for 100 milliseconds because the client IP exceeded the requests-per-second limit.
If the request queue for the IP-URI pair is full, Knewton will respond with an HTTP 429 error with
an X-Knewton-Rate-Exceeded: ip-limited header.
Knewton limits the rate of requests made per access token and API endpoint (HTTP Method & URI). Token-based rate limits vary by endpoint.
Refer to Authentication and Authorization to learn how to authenticate and acquire an access token for the partner admin account.
When a client exceeds a token-based rate limit, Knewton will respond with an HTTP 429 error with an an
X-Knewton-Rate-Exceeded: token-limited header.
Note, again, that although Knewton can issue a separate access token to each User Account ( see Legacy Fine-Grained Authentication), we strongly recommend that a partner application make all requests with a single access token granted to the partner admin account.
Please inform your Knewton representative if you plan to follow the recommended single-token approach.
Finally, Knewton may limit the rate of requests to an endpoint across all partner access tokens. Again, such limits may vary by endpoint.
When a client exceeds a partner-based rate limit, Knewton will respond with an HTTP 429 error with an an
X-Knewton-Rate-Exceeded: partner-limited header.
There is no default partner-based rate limit for most API endpoints. Speak with your Knewton representative to determine appropriate limits.
When Knewton responds with a 429 Error, a partner application should assume that Knewton has not processed any part of the request. The application should be prepared to wait for some time for the rate limit quota to replenish, and then resend the request. Consider applying an exponential backoff strategy to determine the time to delay each attempt to resend.
Note that exhausting the quota on one endpoint does not mean that the application must wait to make calls to other endpoints.
The following flowchart summarizes how Knewton applies IP address, token and partner-based rate limits:
The Knewton API maintains a set of rate limits for different endpoints within the system. The table below specifies these limits.
| Action | Endpoint | Rate Limit |
|---|---|---|
| Account and Auth | ||
| Account create | POST /accounts | 750/min/token |
| Account create (batch) | POST /batch | 90/min/token |
| Account current | GET /accounts/current | 15/min/token |
| Account get ID | GET /accounts/{id} | 15/min/token |
| Account delete | DELETE /accounts/{id} | 150/min/token |
| Registrations | ||
| Registration create | POST /registrations | 375/min/token |
| Registraton get | GET /registrations/{id} | 15/min/token |
| Registration delete | DELETE /registrations/{id} | 375/min/token |
| Learning Instances | ||
| Learning Instance create | POST /learning-instances | 750/min/token |
| Learning Instance get | GET /learning-instances | 15/min/token |
| Learning Instance get (id) | GET /learning-instances/{id} | 15/min/token |
| Learning Instance get registrations | GET /learning-instances/{id}/registrations | 15/min/token |
| Goals | ||
| Goal creation | POST /learning-instances/{id}/scoped-goals | 90/min/token |
| Goal update | PUT /learning-instances/{id}/scoped-goals/{goal_id} | 90/min/token |
| Goal assignment (individual) | PUT /learning-instances/{learning_instance_id}/scoped-goals/ {goal_id}/registrations/{registration_id} | 135/min/token |
| Goal assignment (batch) | PUT /learning-instances/{learning_instance_id}/scoped-goals/ {goal_id}/registrations | 10 assigns/min/token or 100 unassigns/min/token |
| Goal assignment check | GET /learning-instances/{learning_instance_id}/scoped-goals/ {goal_id}/registrations/{registration_id} | 15/min/token |
| Goal assignment delete | DELETE /learning-instances/{learning_instance_id}/scoped-goals/ {goal_id}/registrations/{registration_id} | 135/min/token |
| Events | ||
| Student Events ungraded | POST /registrations/{id}/ungraded-events | 15/min/token |
| Student Events graded | POST /registrations/{id}/graded-events | 15/min/token |
| Focus events | POST /registrations/{id}/focus-events | 15/min/token |
| Recommendation followed | POST /registrations/{id}/recommendation-followed-events | 15/min/token |
| Batch Events | POST /registrations/{id}/batch-events | 15/min/token |
| Recommendations | ||
| Recommendation get | GET /registrations/{id}/recommendation?goal_id={goal_id} | 15/min/token |
| Analytics | ||
| Expected Score for learning instance | POST /learning-instances/{id}/metrics/expected-score/rows | 225/min/token |
| Readiness Forecast for learning instance | POST /learning-instances/{id}/metrics/readiness-forecast/rows | 225/min/token |
| Active Time for taxon(s) or goal(s) for learning instance | POST /learning-instances/{id}/metrics/active-time/rows | 225/min/token |
| Proficiency for learning instance | POST /learning-instances/{id}/metrics/proficiency/rows | 225/min/token |
| Expected Score for registration | POST /registrations/{id}/metrics/expected-score/rows | 225/min/token |
| Readiness Forecast for registration | POST /registrations/{id}/metrics/readiness-forecast/rows | 225/min/token |
| Active Time for taxon(s) or goal(s) for registration | POST /registrations/{id}/metrics/active-time/rows | 225/min/token |
| Proficiency for registration | POST /registrations/{id}/metrics/proficiency/rows | 225/min/token |
| Predicted Score for account(s) | POST /accounts/metrics/predicted-score | 140/min/partner |
| Status and Progress for learning instance | POST /learning-instances/{id}/metrics/status-and-progress | 225/min/token |
| Status and Progress for registration | POST /registrations/{id}/metrics/status-and-progress | 225/min/token |
| Smart Groupings | ||
| Learners to Watch | POST learning-instances/{id}/metrics/groups | 25/min/token |
Getting Started
Working with Adaptive Assignments
Predictive Learner Analytics
General API Usage
Brand Guidelines
Glossary