Overview
The MaestroQA API allows users to access and interact with their quality assurance data programmatically. By using the API, users can automate repetitive tasks, integrate MaestroQA with other tools, and build custom applications that leverage their QA data. In this article, we'll explore the main features of the MaestroQA API, show examples of how it can be used, and provide guidance on how to get started.
Whether you're a seasoned developer or new to APIs, this article will help you understand how to unlock the full potential of MaestroQA by using its API.
Table of Contents
Raw Grading Export (grading data)
Audit Logs Export (activity log data)
Screen Capture Stats (usage data)
Authentication
In order to make requests to the Maestro QA API, you must attach a valid API token to your request.
Obtaining an API Token
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.
Authenticating Requests
An API token must be provided for all requests. The token should be passed in the request's headers, in the format:
'apitoken': 'YOUR_API_TOKEN'
Example (Python)
import requests
headers = {
'Content-Type': 'application/json',
'apitoken': 'YOUR_API_TOKEN'
}
response = requests.get(url, headers=headers)
Certain endpoints allow tokens to be passed in the request body (noted in the endpoint's documentation); this is supported for backward compatibility only and is subject to change.
__________________________________________________________________
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
If a parameter is optional, it may be omitted from the request parameters. If an optional parameter is included, it must contain a valid value.
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
Name | Type | Description |
startDate* | string (see formats) | Include grades that were updated after this date |
endDate* | string (see formats) | Include grades that were updated before this date |
name | string | Name for the export. Defaults to a randomly generated name |
singleFileExport | enum (individual_answers, section_scores, total_scores, annotations, csat) | Specify a single (optional) |
includeCalibrations | enum (all, none, only) | Specify whether calibration scores should be included in the export.
(optional) |
includeGraderQA | boolean | Specify whether grader QA benchmark scores should be included in the export. Default is (optional) |
apiToken | string | See authentication |
Response
The ID of the export that was requested - used to track the export's status and retrieve its results.
Name | Type | Description |
exportId | string | ID of the export that was requested |
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/request-raw-export'
payload = {
'startDate': '2018-08-13T00:00:00Z',
'endDate': '2018-08-19T00:00:00Z',
'name': 'Weekly Maestro Grades Export'
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.post(url, json=payload, headers=headers)
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
Name | Type | Description |
exportId* | string | The ID of the export whose results should be returned |
apiToken | string | See authentication |
Response
Status and result data for the requested export
Name | Type | Description |
status | enum (requested, in_progress, complete, errored) | The status of the export |
dataUrl | string | If status is "complete" and there is data to download, contains the URL to download the export. Otherwise, contains an empty string. |
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 = {
'exportId': 'THE_EXPORT_ID'
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.get(url, json=payload, headers=headers)
Example Response
{
'status': 'complete',
'dataUrl': 'https://subdomain.s3.amazonaws.com/path/to/file'
}
Here is a Data Dictionary for the files contained within the resulting export.
__________________________________________________________________
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
Name | Type | Description |
name | string | Name for the export. Defaults to a randomly generated name |
includeUnavailable | boolean | Whether to include all agents, or just those currently marked “available”. Default is (optional) |
apiToken | string | See authentication |
Response
The ID of the export that was requested - used to track the export's status and retrieve its results.
Name | Type | Description |
exportId | string | ID of the export that was requested |
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/request-groups-export'
payload = {
'name': 'Maestro Agent Groups Export',
'includeUnavailable': False
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.post(url, json=payload, headers=headers)
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
Name | Type | Description |
startDate* | string (see formats) | Include logs that were created after this date |
endDate* | string (see formats) | Include logs that were created before this date |
name | string | Name for the export. Defaults to a randomly generated name |
apiToken | string | See authentication |
Response
The ID of the export that was requested - used to track the export's status and retrieve its results.
Name | Type | Description |
exportId | string | ID of the export that was requested |
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/request-audit-log-export'
payload = {
'startDate': '2018-08-13T00:00:00Z',
'endDate': '2018-08-19T00:00:00Z',
'name': 'Maestro Activity Log Export',
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.post(url, json=payload, headers=headers)
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
Name | Type | Description |
groupIds* | array[string] | IDs of the agent groups whose data should be included in the screen capture usage stats |
interval* | enum (day, week, month) | Time interval for data returned in screen capture usage stats (required) |
apiToken | string | See authentication |
Response
List of data for agents in the specified groups who have used the extension during the given time interval.
Name | Type | Description |
data | array[object] | Screen recording stats for each agent |
data.agentId | string | The agent's id |
data.numberExpectedRecordings | number | Number of recordings expected for this time interval |
data.numberRecordings | number | Actual number of recordings for this time interval |
data.percentRecorded | number | Percent of tickets recorded |
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/screen-capture-usage-stats'
payload = {
'groupIds': ['123'],
'interval': 'day',
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.post(url, json=payload, headers=headers)
Example Response
{
'data': [
{ 'agentId': 'abc',
'numberExpectedRecordings': 10,
'numberRecordings': 1,
'percentRecorded': 10 },
{ 'agentId': 'def',
'numberExpectedRecordings': 5,
'numberRecordings': 1,
'percentRecorded': 20 }
]
}
__________________________________________________________________
Create a Ticket
Create a new Ticket in your MaestroQA account.
Definition
POST https://app.maestroqa.com/api/v1/tickets
Body Parameters
Name | Type | Description |
gradable_id* | string | A unique identifier for the ticket. (required)
Note: this id must be unique - if the id is in use by any other ticket in your account, the request will fail with a 409 Conflict error |
type* | string | The ticket type/source from your external support system (required) |
subject* | string | The ticket's subject (required) |
agents* | array[string] | A list of the IDs of agents associated with the ticket (required)
See Guide to User Roles for information about Agent IDs |
link* | string | A link to the ticket in your external resource (required) |
body* | string | The text content of the ticket (required) |
tags | string | The ticket's tags, formatted as a comma-separated string |
status | string | The ticket's status (ex: "Closed") |
csat_score | number | The CSAT score for the ticket |
first_seen | string (see formats) | The date the ticket was created
Defaults to the current date |
last_seen | string (see formats) | The date of the last activity on the ticket
Defaults to the current date |
attributes | object | Custom attributes for the ticket
Note: these attributes must already exist in your MaestroQA account. The values passed for each key will be validated against the attribute's expected value type (ex: string, boolean, etc.). Unrecognized attributes will be ignored. |
Response
The ticket that was created
Name | Type | Description |
gradable_id | string | A unique identifier for the ticket. |
type | string | The ticket type/source from your external support system |
subject | string | The ticket's subject |
agents | array[string] | A list of the IDs of agents associated with the ticket |
link | string | A link to the ticket in your external resource |
body | string | The text content of the ticket |
tags | string | The ticket's tags, formatted as a comma-separated string |
status | string | The ticket's status |
csat_score | number | The CSAT score for the ticket |
first_seen | string (see formats) | The date the ticket was created |
last_seen | string (see formats) | The date of the last activity on the ticket |
attributes | object | The ticket's custom attributes |
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/tickets'
payload = {
'gradable_id': 'unique_ticket_id',
'type': 'custom helpdesk',
'subject': 'New ticket',
'link': 'http://www.mynewticket.com',
'body': 'The text content of this ticket',
'status': 'open',
'agents': ['this_agent_id'],
'tags': 'login,support,escalated',
'csat_score': 5,
'first_seen': '2022-02-02T00:00:00.000Z',
'last_seen': '2022-03-07T00:00:00.000Z',
'attributes': {
'public_comment_count': 5,
'group': 'Support',
'first_resolution_time_total_minutes': 1023
}
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.post(url, json=payload, headers=headers)
Example Response
{
'_id': 'unique_maestro_id_for_ticket',
'gradable_id': 'unique_ticket_id',
'type': 'custom helpdesk',
'subject': 'New ticket',
'link': 'http://www.mynewticket.com',
'body': 'The text content of this ticket',
'status': 'open',
'agents': ['this_agent_id'],
'tags': 'login,support,escalated',
'csat_score': 5,
'first_seen': '2022-02-02T00:00:00.000Z',
'last_seen': '2022-03-07T00:00:00.000Z',
'attributes': {
'public_comment_count': 5,
'group': 'Support',
'first_resolution_time_total_minutes': 1023
}
}
__________________________________________________________________
Update a Ticket
Update an existing Ticket in your MaestroQA account.
Note: tickets synced from helpdesk integrations cannot be manually updated
Definition
PATCH https://app.maestroqa.com/api/v1/tickets/:gradable_id
Path Parameters
Name | Type | Description |
gradable_id* | string | The unique identifier for the ticket (required) |
Body Parameters
Name | Type | Description |
type | string | The ticket type/source from your external support system |
subject | string | The ticket's subject |
agents | array[string] | A list of the IDs of agents associated with the ticket
See Guide to User Roles for information about Agent IDs |
link | string | A link to the ticket in your external resource |
body | string | The text content of the ticket |
tags | string | The ticket's tags, formatted as a comma-separated string |
status | string | The ticket's status (ex: "Closed") |
csat_score | number | The CSAT score for the ticket |
first_seen | string (see formats) | The date the ticket was created |
last_seen | string (see formats) | The date of the last activity on the ticket |
attributes | object | Custom attributes for the ticket
Note: these attributes must already exist in your MaestroQA account. The values passed for each key will be validated against the attribute's expected value type (ex: string, boolean, etc.). Unrecognized attributes will be ignored. |
Response
The updated ticket
Name | Type | Description |
gradable_id | string | A unique identifier for the ticket. |
type | string | The ticket type/source from your external support system |
subject | string | The ticket's subject |
agents | array[string] | A list of the IDs of agents associated with the ticket |
link | string | A link to the ticket in your external resource |
body | string | The text content of the ticket |
tags | string | The ticket's tags, formatted as a comma-separated string |
status | string | The ticket's status |
csat_score | number | The CSAT score for the ticket |
first_seen | string (see formats) | The date the ticket was created |
last_seen | string (see formats) | The date of the last activity on the ticket |
attributes | object | The ticket's custom attributes |
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/tickets/unique_ticket_id'
payload = {
'subject': 'Updated subject!',
'status': 'closed',
'last_seen': '2022-03-15T00:00:00.000Z'
}
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.patch(url, json=payload, headers=headers)
Example Response
{
'_id': 'unique_maestro_id_for_ticket',
'gradable_id': 'unique_ticket_id',
'type': 'custom helpdesk',
'subject': 'Updated subject!',
'link': 'http://www.mynewticket.com',
'body': 'The text content of this ticket',
'status': 'closed',
'agents': ['this_agent_id'],
'tags': 'login,support,escalated',
'csat_score': 5,
'first_seen': '2022-02-02T00:00:00.000Z',
'last_seen': '2022-03-15T00:00:00.000Z'
}
__________________________________________________________________
Delete a Ticket
Delete an existing Ticket in your MaestroQA account.
Note: tickets synced from helpdesk integrations cannot be manually deleted
Definition
DELETE https://app.maestroqa.com/api/v1/tickets/:gradable_id
Path Parameters
Name | Type | Description |
gradable_id* | string | The unique identifier for the ticket (required) |
Response
N/A - successful delete requests will receive a 200 OK
response
Example Request (Python)
import requests
url = 'https://app.maestroqa.com/api/v1/tickets/unique_ticket_id'
headers = { 'apitoken': 'YOUR_API_TOKEN' }
response = requests.delete(url, headers=headers)
__________________________________________________________________
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.