# Throttling

To ensure the best possible performance and reliability of Cornerstone's APIs, we have implemented throttle limits. The throttling limits vary per API and are listed in the specific documentation for the API within the Developer Portal. Please note the following:

  • Throttle limits apply to all authenticated APIs calls.
  • Throttle limits are for each environment. For example, if an API has a limit of 1000 requests per hour, that means you can make 1000 requests each in Pilot, Stage, and Production environments.

If a request is made after the throttle limit is reached, Cornerstone will respond with the following HTTP 429 error, which is to be handled elegantly. We recommend that your applications queue such requests until the throttle limit duration has passed after which the request can be re-sent.

// Throttle Limit Error
{
    "status": "429",
    "timeStamp": "2018-05-15T18:06:55+0000",
    "error": {
        "errorId": "77ed61e0-7052-4fad-b265-c52679ab2cac",
        "message": "CSOD Too many requests.",
        "code": "429",
        "description": null,
        "details": null
    }
}

# Throttling Status

There are two API response HEADERS that can be inspected to see the throttling status per hour. The former indicates the throttling limit (per hour), while the latter indicates how many requests are left in the current hour.

  • x-csod-throttling-rate-limit-urilevel
  • x-csod-requests-remaining-urilevel

Throttling limits are also maintained at the minute level (x-csod-throttling-rate-limit-urilevel / 60). If you hit that limit, you will get throttled for the remainder of that minute.

# Best Practices

  • Customers are encouraged to maintain a timer on their end, to pause their calls as soon as they hit their minute limit (HTTP 429), then start once the minute elapses.
  • If it's been a while since customers synched their data from Cornerstone, they should control the requests they issue to us instead of trying to rush through as quickly as possible and hitting their throttling limits.
  • HTTP 429 calls also count against customer’s aggregate limits, which means they may end up hitting their 1-hour limit sooner and must wait a longer time for their window to open again, even though their minute limit is available.

# Throttling Limits

API Throttling Limit
Employee APIs Throttling Limit
OU APIs Throttling Limit
Learning Assignment APIs Throttling Limit
Express Class API Throttling Limit
Transcript APIs Throttling Limit
Reporting APIs Throttling Limit
Bulk APIs Throttling Limit
Job Application API Throttling Limit
Candidate API Throttling Limit
Foundational APIs See below

# Foundational APIs

The generic throttling limit across all Foundational APIs is 417 requests per minute, 25,000 requests per hour and 600,000 requests per day.

The following APIs are part of the generic Foundational APIs throttling limits:

API Method Url Description
Global Search GET /services/api/Core/GlobalSearch Retrieve training data based on your specific search criteria.
OU (Legacy) GET /services/api/OrgUnits/OU Get OU data (legacy)
Approvals GET /services/api/Employee/{userName}/approvals Fetch all pending approval items for the supported approval types for a given user.
Approvals POST /services/api/Employee/{userName}/approvals Approve or deny a pending approval item.
Custom Field GET /services/api/CustomField/ Learning Object (LO) level or the Transcript level.
Training Unit POST /services/api/TrainingUnit/ Create Training Unit Assignment used in Extended Enterprise module
Session Roster POST /services/api/SessionRoster/ Update the session attendance roster as well as complete the session.
Get Details GET /services/api/SessionRoster/GetSessionRoster Retrieve the roster details of an ILT Session.
Get LO GET /services/api/LO/GetDetails Retrieve details of a learning object (LO)
Create LO POST /services/api/LO/Create Create new Learning Objects (Event, Session, Online Course, and Material)
Update LO PUT /services/api/LO/Update Update existing ILT Sessions.
Transcript Search GET /services/api/LOTranscript/TranscriptSearch Retrieve users’ transcript information
Transcript and Task - Inbox Items GET /services/api/TranscriptAndTask/Inbox Retrieves all items in the user’s inbox as shown on the Welcome Page widget in the Cornerstone UI.
Transcript and Task - Suggested Training GET /services/api/TranscriptAndTask/SuggestedTraining Retrieve training with availability type: Suggested.
Transcript and Task - Tasks GET /services/api/TranscriptAndTask/Task Retrieve all incomplete tasks assigned to the user.
Transcript and Task - Approvals GET /services/api/TranscriptAndTask/Approval Retrieve the pending approvals for a manager or approver.
Transcript and Task - Assigned Trainings GET /services/api/TranscriptAndTask/Assigned Retrieve all training assigned to a user, along with their statuses and due dates as applicable
Transcript and Task - Sessions GET /services/api/TranscriptAndTask/Session Retrieve the upcoming sessions in a user's transcript.
Transcript and Task - Transcripts GET /services/api/TranscriptAndTask/Transcript Retrieve transcript records for a user.
Certification - Delete POST /services/api/Certification/Remove Remove certifications that are assigned to users.
Certification - Detals GET /services/api/CertificationDetails/GetCertificationDetails Retrieve a certification's details, including section-level details.
Certification - Transcript GET /services/api/CertificationTranscript/CertificationTranscriptDetails Retrieve certification details from a user's transcript.
Performance Review - Get Details GET /services/api/Review/PerformanceReview Extract performance review data that is associated with a performance review task
Goals - Create POST /services/api/Goals/Create Create new user goals.
Goals - Update PUT /services/api/Goals/Update Update existing user goals
Goals - Update Progress PUT /services/api/Goals/UpdateProgress Opdate a user's progress on a goal.
Goals - Details GET /services/api/Goals/GetDetails Retrieve details of user goals
Goals - Cancel PUT /services/api/Goals/UpdateStatus Update goal statuses to cancelled
Goals - Lock PUT /services/api/Goals/LockResults Lock or unlock goals
Requisition - Details GET /services/api/Recruiting/JobRequisitionDetails Retrieve job requisition details
Requisition - Ad Details GET /services/api/Recruiting/JobRequisitionDetails/Ad Retrieve internal, external, and mobile job ads for a given job requisition
Requisition - Custom Fields GET /services/api/Recruiting/JobRequisitionDetails/CustomField Retrieve custom fields for a given job requisition
Applicants - Details GET /services/api/Recruiting/JobApplicant Retrieve job applicants in a given status.
Applicants - Custom Fields GET /services/api/Recruiting/JobApplicant/CustomFields Retrieve job applicant details including applicant custom fields
Applicants - Update Status PUT /services/api/Recruiting/JobApplicantUpdateStatus update an applicant's status
Applicants - Update Status PUT /services/api/Recruiting/JobApplicantUpdateStatus update an applicant's status