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: 
  1. Total rubric scores
  2. Section scores
  3. Individual answer scores
  4. Annotations
  5. 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.

Did this answer your question?