Reporting API Endpoints

Endpoints included in the API for reporting are private endpoints and do not come with a deprecation policy at this time. Anthology Ally may change or update these endpoints depending on our roadmap or future releases.

Review the following technical documentation to learn how to appropriately set up and customize your endpoints. Feel free to check how to Integrate Ally's API with an External Reporting Tool for additional guidance. 

Available methods

The Ally API for reporting has two methods. The following section describes them: 

Replace [Ally Client ID] with your Ally ID. If you do not know your ID, you can create a support ticket to request it.

Replace [Region] depending on the region where the Ally environment of your institution is hosted:

• US data center: prod.ally.ac
• Canadian data center: prod-ca-central-1.ally.ac
• European data center: prod-eu-central-1.ally.ac
• Singapore data center: prod-ap-southeast-1.ally.ac
• Australian data center: prod-ap-southeast-2.ally.ac

The information above may vary depending on the LMS.  You can review the column definition in the Course Report Documentation for each LMS:

• Blackboard Learn
• Moodle
• D2L Brightspace
• Instructure Canvas

HTTP Status Response 

The Ally API includes an status field in the metadata as follows:

• Status 200 - Successful: Your request was received successfully and the requested dataset is part of the response. 
• Status 202 - Processing: Your request was received successfully but the dataset is under preparation, and is not available yet. Repeat your request after some time (at least one minute is recommended).
• Status 401 - Unauthorized: The Ally Client ID or the authorization token are not correct.
• Status 400 - Bad request: The URL has an invalid parameter name, for example, an unknown filter option, operator or value. Review the syntax of the URL. Remember that some of the filter and sorting options are case sensitive. 

Methods Documentation 

Method: Overall  

HTTP request: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall 

Replace [Ally Client ID] with your Ally ID. If you do not know your ID, you can create a support ticket to request it.  

Replace [Region] depending on the region where the Ally environment of your institution is hosted:

• US data center: prod.ally.ac
• Canadian data center: prod-ca-central-1.ally.ac
• European data center: prod-eu-central-1.ally.ac
• Singapore data center: prod-ap-southeast-1.ally.ac
• Australian data center: prod-ap-southeast-2.ally.ac

Authorization: OAuth bearer token. 

Parameters: Optional filters or sorting options. 

Request Body: None 

Response: 

{ 
    "data": [ 
        { 
            "application/x-quiz": 2, 
            "observedDeletedOn": "", 
            "termName": "Fall 2016", 
            "courseId": "1", 
            "application/x-announcement": 0, 
            "image": 4, 
            "termId": "2", 
            "document": 93, 
            "allyEnabled": true, 
            "pdf": 74, 
            "courseCode": "BIO101", 
            "application/x-assignment": 0, 
            "departmentId": "1", 
            "totalFiles": 192, 
            "courseUrl": "https://ally.instructure.com/courses/1", 
            "departmentName": "Anthology Ally", 
            "application/x-page": 1, 
            "filesScore": 0.6022810739019293, 
            "application/x-syllabus": 1, 
            "numberOfStudents": 1, 
            "html-page": 5, 
            "lastCheckedOn": "2022-04-13 15:33:23", 
            "WYSIWYGScore": 1.0, 
            "totalWYSIWYG": 5, 
            "courseName": "Biology 101", 
            "application/x-discussion-topic": 1, 
            "other": 11, 
            "overallScore": 0.6129724428830603, 
            "presentation": 5 
        } 
], 
    "metadata": {
    "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "Processing", 
        "from": 1 
    } 
} 

Method: Issues 

HTTP request: GET 
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall 

Replace [Ally Client ID] ID with your Ally ID. If you do not know your ID you can create a support ticket to request it. 

Replace [Region] depending on the region where the Ally environment of your institution is hosted:

• US data center: prod.ally.ac
• Canadian data center: prod-ca-central-1.ally.ac
• European data center: prod-eu-central-1.ally.ac
• Singapore data center: prod-ap-southeast-1.ally.ac
• Australian data center: prod-ap-southeast-2.ally.ac

Authorization: OAuth bearer token  

Parameters: Optional filters or sorting options. 

Request Body: None 

Response: 

{ 
    "data": [ 
        { 
            "imageDecorative2": 4, 
            "htmlEmptyHeading2": 0, 
            "imageSeizure1": 2, 
            "observedDeletedOn": "", 
            "htmlObjectAlt2": 0, 
            "security1": 3, 
            "termName": "Fall 2016", 
            "courseId": "1", 
            "languageCorrect3": 14, 
            "htmlColorContrast2": 2, 
            "htmlLinkName3": 0, 
            "termId": "2", 
            "languagePresence3": 10, 
            "allyEnabled": true, 
            "htmlLabel2": 0, 
            "alternativeText2": 68, 
            "htmlImageAlt2": 0, 
            "htmlImageRedundantAlt3": 0, 
            "headingsPresence2": 20, 
            "courseCode": "BIO101", 
            "headingsSequential3": 4, 
            "departmentId": "1", 
            "htmlHeadingsPresence2": 0, 
            "courseUrl": "https://ally.instructure.com/courses/1", 
            "headingsStartAtOne3": 4, 
            "departmentName": "Anthology Ally", 
            "htmlHeadingsStart2": 0, 
            "htmlTdHasHeader2": 0, 
            "htmlList3": 0, 
            "htmlDefinitionList3": 0, 
            "htmlCaption2": 0, 
            "tableHeaders2": 23, 
            "htmlEmptyTableHeader2": 0, 
            "htmlHasLang3": 1, 
            "ocred2": 0, 
            "scanned1": 6, 
            "htmlBrokenLink2": 0, 
            "numberOfStudents": 1, 
            "htmlHeadingOrder3": 0, 
            "lastCheckedOn": "2022-04-13 15:33:23", 
            "headingsHigherLevel3": 0, 
            "contrast2": 28, 
            "title3": 46, 
            "imageOcr3": 0, 
            "tagged2": 4, 
            "libraryReference": 172, 
            "courseName": "Biology 101", 
            "imageContrast2": 0, 
            "imageDescription2": 4, 
            "htmlTitle3": 1, 
            "parsable1": 2 
        } 
], 
    "metadata": { 
        "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "Processing", 
        "from": 1 
    } 
} 

Where: 

• Data: contains the data set of the results. 
• Metadata: 
  • To: record to which data will be fetched, it's “offset” + “limit” or “total” if the sum exceeds “total”. 
  • From: record from which data will start, it's “offset” + 1. 
  • Total: total number of courses considered by Ally in the LMS instance. 

Offset - from which record start 

• First row is offset = 0, 
• When offset < 0, then the user gets error 400 - [Invalid value (parameter=offset, message=No such data)], 
• When (offset >= total) => then user gets error 400 - [Invalid value (parameter=offset, message=No such data)] 

Limit - how many records are retrieved beginning from offset 

• When (limit < 1), then the user gets error 400 - [Invalid value (parameter=limit, message=Limit out of boundaries)]
• When (limit > 10000) then the user gets error 400 - [Invalid value (parameter=limit, message=Limit out of boundaries)] 
• When (offset < total && offset + limit > total), then we change the limit in the background for you, and data will be retrieved until last (total) 

Filters and sorting options 

Endpoint responses can be filtered in the URL. This section describes the available options: 

Sorting options 

You can define if you want to display the results sorted in ascending or descending order considering one criterion. If you need to add a sorting option, you must add the sorting parameter as described below:

endpoint-url?sort=<Sort parameter value> 

Where <Sort parameter value> can be any of the following parameter values: 

Parameter values are case-sensitive, and only one sorting option can be used at a time. 

By default, results are sorted in ascending order. If you want to set a different order, you can add the order parameter: 

endpoint-url?sort=<Sort parameter value>&order=<Order value> 

Where <Order value> can be: asc or desc 

Example: 

https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc 

Filtering options 

You can use filtering options to obtain smaller or reduced responses based on the selected criteria.  If you need to add a filtering option, you must add the filtering parameter as described below:

Filter Parameters (without operator) 

 endpoint-url?<Filter Parameter>=<value> 

Filter Parameters (with operator) 

endpoint-url?<Filter Parameter>=<Operator>:<value> 

Where: 

• <Filter Parameter>: Filtering parameter to get a smaller set of results. You can consult the supported parameters in the table below. 
• <Operator>: You must use an operator to filter, like equal, not equal. 
• <value>: Value used in the filter. 

Parameter values are case-sensitive.

Supported Operators

The following table contains the supported operators based on the field type: 

Example: 

The following example retrieves all the courses that contain the keyword "tests" in the course name:

https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests 

Using multiple filters 

You can combine the sorting and filtering options in the same endpoint URL by adding the "&" character between the two conditions. For example, let's say you want to retrieve all the courses that contain the keyword "test" in the course name where Ally is enabled, and that the overall score Is less than 90%. The URL would look like this:

https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9

You can also use two filtering options. For example, let's say you need to obtain all the courses that have an overall score between 10% and 70%:

https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7