MaestroQA API

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!

Table of Contents

• Authentication & API Tokens

• Endpoints

  • Raw Grading Export (grading data)

  • Retrieve Export Results

  • Agent Groups Export

  • Audit Logs Export (activity log data)

  • Screen Capture Stats (usage data)

• Rate Limits

Authentication - Obtaining API Token

In order to make requests to the MaestroQA API, you must attach a valid API token to your request. API tokens can be generated in the MaestroQA dashboard on the Other Settings page.

Within "Other Settings", scroll down to the API Tokens section and 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.

__________________________________________________________________

Formats

1. All dates should be UTC offset datetime strings, formatted according to the extended ISO 8601 format (reference)

[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z

ex. 2017-12-13T05:00:00Z

2. Each endpoint’s request parameters and response content should be JSON-encoded

Endpoints

The * symbol is used to denote required parameters

Request A “Raw” Export

Raw exports are the equivalent to the Raw CSV export in the MaestroQA dashboard. The export will include grades that were last updated between the specified start date and end date.

Raw exports generate a zip file containing a CSV for each level of rubric scores:

• total rubric scores

• section scores

• individual answer scores

• annotations

• CSAT

Definition

POST https://app.maestroqa.com/api/v1/request-raw-export

Body Parameters

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-raw-export'

payload = {
    'apiToken': 'YOUR_API_TOKEN',
    'startDate': '2018-08-13T00:00:00Z',
    'endDate': '2018-08-19T00:00:00Z',
    'name': 'Weekly Maestro Grades Export'
}

response = requests.post(url, json=payload)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

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.

Definition

GET https://app.maestroqa.com/api/v1/get-export-data

Header or Body Parameters

Response

Status and result data for the requested export

Note: if there was no matching 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 nothing to download.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/get-export-data'

payload = {
    'apiToken': 'YOUR_API_TOKEN',
    'exportId': 'THE_EXPORT_ID'
}

response = requests.get(url, json=payload)

Example Response

{
    'status': 'complete',
    'dataUrl': 'https://subdomain.s3.amazonaws.com/path/to/file'
}

__________________________________________________________________

Request an “agent groups” export

An “agent groups” export is the equivalent to the Agent Groups export in the MaestroQA App. This will export all the agent groups and group membership.

Definition

POST https://app.maestroqa.com/api/v1/request-groups-export

Body Parameters

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-groups-export'

payload = {
    'apiToken': 'YOUR_API_TOKEN',
    'name': 'Maestro Agent Groups Export',
    'includeUnavailable': False
}

response = requests.post(url, json=payload)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Request an “audit logs” export

An “audit log” export is the equivalent to the Activity Logs export in the MaestroQA App. This will export all the user activity in your account during the specified date range. See "What Can I Track in the Activity Log" for details on what is tracked in the activity log.

Definition

POST https://app.maestroqa.com/api/v1/request-audit-log-export

Body Parameters

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-audit-log-export'

payload = {
    'apiToken': 'YOUR_API_TOKEN',
    'startDate': '2018-08-13T00:00:00Z',
    'endDate': '2018-08-19T00:00:00Z',
    'name': 'Maestro Activity Log Export',
}

response = requests.post(url, json=payload)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Request Screen Capture Usage Stats

Get the data for your agents' usage of the MaestroQA screen capture tool.

Definition

POST https://app.maestroqa.com/api/v1/screen-capture-usage-stats

Body Parameters

Response

List of data for agents in the specified groups who have used the extension during the given time interval.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/screen-capture-usage-stats'

payload = {
    'apiToken': 'YOUR_API_TOKEN',
    'groupIds': ['123'],
    'interval': 'day',
}

response = requests.post(url, json=payload)

Example Response

{
  'data': [
    { 'agentId': 'abc',
      'numberExpectedRecordings': 10,
      'numberRecordings': 1,
      'percentRecorded': 10 },
    { 'agentId': 'def',
      'numberExpectedRecordings': 5,
      'numberRecordings': 1,
      'percentRecorded': 20 }
  ]
}

__________________________________________________________________

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 there are guidelines to follow:

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

You can expect to export 10,000 to 50,000 scores at time. The exact number is variable based on the size of your scorecard, number of comments per scorecard, and other factors.