Quiz Reports API
API for accessing and generating statistical reports for a quiz
A QuizReport object looks like:
{
// the ID of the quiz report
"id": 5,
// the ID of the quiz
"quiz_id": 4,
// which type of report this is possible values: 'student_analysis',
// 'item_analysis'
"report_type": "student_analysis",
// a human-readable (and localized) version of the report_type
"readable_type": "Student Analysis",
// boolean indicating whether the report represents all submissions or only the
// most recent ones for each student
"includes_all_versions": true,
// boolean indicating whether the report is for an anonymous survey. if true, no
// student names will be included in the csv
"anonymous": false,
// boolean indicating whether the report can be generated, which is true unless
// the quiz is a survey one
"generatable": true,
// when the report was created
"created_at": "2013-05-01T12:34:56-07:00",
// when the report was last updated
"updated_at": "2013-05-01T12:34:56-07:00",
// the API endpoint for this report
"url": "http://canvas.example.com/api/v1/courses/1/quizzes/1/reports/1",
// if the report has finished generating, a File object that represents it.
// refer to the Files API for more information about the format
"file": null,
// if the report has not yet finished generating, a URL where information about
// its progress can be retrieved. refer to the Progress API for more information
// (Note: not available in JSON-API format)
"progress_url": null,
// if the report is being generated, a Progress object that represents the
// operation. Refer to the Progress API for more information about the format.
// (Note: available only in JSON-API format)
"progress": null
}
Retrieve all quiz reports Quizzes::QuizReportsController#index
GET /api/v1/courses/:course_id/quizzes/:quiz_id/reports
url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/reports
Returns a list of all available reports.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
includes_all_versions | boolean |
Whether to retrieve reports that consider all the submissions or only the most recent. Defaults to false, ignored for item_analysis reports. |
Create a quiz report Quizzes::QuizReportsController#create
POST /api/v1/courses/:course_id/quizzes/:quiz_id/reports
url:POST|/api/v1/courses/:course_id/quizzes/:quiz_id/reports
Create and return a new report for this quiz. If a previously generated report matches the arguments and is still current (i.e. there have been no new submissions), it will be returned.
Responses
-
400 Bad Request
if the specified report type is invalid -
409 Conflict
if a quiz report of the specified type is already being generated
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
quiz_report[report_type] | Required | string |
The type of report to be generated.
Allowed values: |
quiz_report[includes_all_versions] | boolean |
Whether the report should consider all submissions or only the most recent. Defaults to false, ignored for item_analysis. |
|
include | String[] |
Whether the output should include documents for the file and/or progress objects associated with this report. (Note: JSON-API only)
Allowed values: |
Get a quiz report Quizzes::QuizReportsController#show
GET /api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id
url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id
Returns the data for a single quiz report.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
include | String[] |
Whether the output should include documents for the file and/or progress objects associated with this report. (Note: JSON-API only)
Allowed values: |
Abort the generation of a report, or remove a previously generated one Quizzes::QuizReportsController#abort
DELETE /api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id
url:DELETE|/api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id
This API allows you to cancel a previous request you issued for a report to be generated. Or in the case of an already generated report, you’d like to remove it, perhaps to generate it another time with an updated version that provides new features.
You must check the report’s generation status before attempting to use this interface. See the “workflow_state” property of the QuizReport’s Progress object for more information. Only when the progress reports itself in a “queued” state can the generation be aborted.
Responses
-
204 No Content
if your request was accepted -
422 Unprocessable Entity
if the report is not being generated or can not be aborted at this stage