Overview
This article will help provide more insight into MaestroQA's API. Please keep in mind, in order to execute the below actions, you must be an Admin user within MaestroQA. With that said, let's get started!
Authentication - Obtaining API Token
In order to make requests to the MaestroQA API, you must attach a valid API token to your request. You can obtain this token in the MaestroQA dashboard.
From the gear icon in the upper righthand corner, navigate to "Other Settings".
Within "Other Settings", scroll down until you see API Tokens. Then click "Create New Token".
By default, API Tokens expire every 90 days for security purposes. This expiration can be turned off, or tokens can be deactivated manually.
__________________________________________________________________
Endpoints
Note:
1. ISOFormat datestrings are of this date format:
[year]-[month]-[day]T[hour]:[minute]:[second]Z
ex. 2017-12-13T05:00:00Z
2. Each endpoint’s request parameters, and response content, are generally expected to be JSON-encoded
Request A “Raw” Export
Kicks off a raw export of grading data, equivalent to the Raw CSV export in the MaestroQA dashboard
POST => https://app.maestroqa.com/api/v1/request-raw-export
Parameters in the request body
apiToken - string
[see Authentication]
startDate - string
ISOFormat datestring (UTC) - the export will include all grades that were updated between the start date and end date.
endDate - string
ISOFormat datestring (UTC) - the export will include all grades that were updated between the start date and end date.
name (optional) - string
Name of export to be created, otherwise a randomly generated name will be created
singleFileExport (optional) - string
Optional parameter specifying to export a single csv file instead of a zip file of all of the export csvs together. The options are the titles of the csvs in the full export: "individual_answers", "section_scores", "total_scores", "annotations", "csat".
*note apiToken can also be sent via headers if preferred, all other parameters must be sent via the body.
Returns
exportId - string - the ID to track this export’s status and retrieve its results
__________________________________________________________________
Retrieve the results of an export
After an export has been requested, check its status and fetch the URL from which to download the export’s results
GET => https://app.maestroqa.com/api/v1/get-export-data
Parameters in the request body or headers
apiToken - string
[see Authentication]
exportId - string
Export ID gathered from API calls to endpoints such as:
‘request-raw-export’ or ‘request-groups-export’
Returns
status - string
The status of the export, one of ['requested', 'in_progress', 'complete', 'errored']
dataUrl - string
If status is 'completed', dataUrl will be an S3 URL from which a file can be downloaded. Otherwise dataUrl will be empty.
Note if there is no grading data for the parameters requested (ex. if you request dates in the future), the dataUrl field will be empty, even when the status is 'complete' as there is no S3 file of data to download.
The format of the downloaded file depends on the export type:
- For “raw” exports, the file is a zipped folder unless the singleFileExport parameter is passed. When unzipped, the folder contains a CSV for each level of the rubric scores:
- Total rubric scores
- Section scores
- Individual answer scores
- Annotations
- CSAT
This file format is the same as the Raw Export in the MaestroQA dashboard. For documentation on the format, see this help article:
- If the singleFileExport parameter is passed, a single CSV file with the file type specified is generated.
- For “group” exports, the file is a CSV.
__________________________________________________________________
Request a “groups” export
Kicks off a “groups” export, equivalent to the Groups export in the MaestroQA dashboard. This will export all the groups and agent membership
POST => https://app.maestroqa.com/api/v1/request-groups-export
Parameters in the request body
apiToken - string
[see Authentication]
name (optional) - string
name of export to be created
includeUnavailable (optional, defaults to false) - boolean
whether to include all agents, or just those currently marked “Available”
Returns
exportId - string - the ID to track this export’s status and retrieve its results
__________________________________________________________________
Rate Limits
A given token has limits on how many times it can be used to make a request. These limits are subject to change, but will start out in these ballparks:
Demanding endpoints (such as requesting an export)
1 request per second
30 requests per minute
Easy endpoints (such as retrieving an export’s status and data url)
10 requests per second
100 requests per minute
Note you may typically export 10,000 to 50,000 scores at time, but the exact number is variable based on the size of your scorecard, number of comments per scorecard, and other factors.