Cloud Academy's API support for reports lets enterprises automate report generation and retrieval. With the report API, you can integrate your Cloud Academy reports directly into your corporate dashboards so you can understand your teams' progress in a central location. The reports API functionality is predictable and reliable.
This article contains the following sections:
Process Overview
The report API expects the following standard workflow:
- The requestor performs a POST request to the endpoint for the desired report.
The body of the request contains parameters to specify the output format for the report (Excel file or ZIP file containing CSV) and the details to filter the data on the report, such as user ID, team ID, or date range. You can find the specific parameters for each report type in the Reports section of the API documentation. - Cloud Academy validates the credentials and request.
- Cloud Academy creates a reporting job and returns a unique job ID to the requestor.
- The requestor performs a GET request to periodically check the job status using the unique job ID. When the job status returns DONE, it includes the report URL.
- The requestor retrieves the report from the URL. The URL expires after 10 minutes, after which it is not functional.
While in transit, the APIs are protected by SSL (HTTPS).
Using the Reports API
You can find the list of endpoints, parameters, and code samples on the Cloud Academy API documentation.
Authentication
The reports API is a part of the larger Cloud Academy API, which requires requestors to use an API key pair to generate an authentication token. You can read more about generating an authentication token in Generating an Authentication Token.
Special Throttling for Reports
For general use, the Cloud Academy limits the public API to one call per minute. However, for reports, an additional limit exists of one report of each type per user per hour.
If a user attempts to request a second copy of the report within the hour, the API returns a 429 Too Many Requests error. The error includes the length of time the user must wait before successfully retrying.
Note: The one report of each type per user per hour also applies to the application interface. If a user requests a report using the API, that user must wait an hour before requesting the same report through the user interface.
Content-type Header
All requests must contain the following content-type header:
application/vnd.api+json
Available Reports
The following reports are available to request with the API:
- Company Usage Report: The User Usage report for all members of the company.
- Team Usage Report: Generates the User Usage Report for all members of the team the parameters specify.
- User Usage Report: Generates the User Usage Report for the user the parameters specify.
- Consumption Content Report: Generates the Product Consumption Report.
- Consumption Learning Paths Report: Generates the Learning Paths Consumption Report.
- Consumption Training Plans: Generates the Training Plan Consumption Report.
- Members Report: Exports the member data for the members in the account.