Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • Studio API
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page
  • Get all quiz submissions.
  • Get the quiz submission.
  • Get a single quiz submission.
  • Create the quiz submission (start a quiz-taking session)
  • Update student question scores and comments.
  • Get current quiz submission times.
  • Appendixes
  • Appendix: Manual Scoring
  • More example requests

Was this helpful?

  1. Services
  2. Canvas LMS
  3. Resources

Quiz Submissions

API for accessing quiz submissions

A QuizSubmission object looks like:

{
  // The ID of the quiz submission.
  "id": 1,
  // The ID of the Quiz the quiz submission belongs to.
  "quiz_id": 2,
  // The ID of the Student that made the quiz submission.
  "user_id": 3,
  // The ID of the Submission the quiz submission represents.
  "submission_id": 1,
  // The time at which the student started the quiz submission.
  "started_at": "2013-11-07T13:16:18Z",
  // The time at which the student submitted the quiz submission.
  "finished_at": "2013-11-07T13:16:18Z",
  // The time at which the quiz submission will be overdue, and be flagged as a
  // late submission.
  "end_at": "2013-11-07T13:16:18Z",
  // For quizzes that allow multiple attempts, this field specifies the quiz
  // submission attempt number.
  "attempt": 3,
  // Number of times the student was allowed to re-take the quiz over the
  // multiple-attempt limit.
  "extra_attempts": 1,
  // Amount of extra time allowed for the quiz submission, in minutes.
  "extra_time": 60,
  // The student can take the quiz even if it's locked for everyone else
  "manually_unlocked": true,
  // Amount of time spent, in seconds.
  "time_spent": 300,
  // The score of the quiz submission, if graded.
  "score": 3,
  // The original score of the quiz submission prior to any re-grading.
  "score_before_regrade": 2,
  // For quizzes that allow multiple attempts, this is the score that will be
  // used, which might be the score of the latest, or the highest, quiz
  // submission.
  "kept_score": 5,
  // Number of points the quiz submission's score was fudged by.
  "fudge_points": 1,
  // Whether the student has viewed their results to the quiz.
  "has_seen_results": true,
  // The current state of the quiz submission. Possible values:
  // ['untaken'|'pending_review'|'complete'|'settings_only'|'preview'].
  "workflow_state": "untaken",
  // Indicates whether the quiz submission is overdue and needs submission
  "overdue_and_needs_submission": false
}

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions

Scope: url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions

Get a list of all submissions for this quiz. Users who can view or manage grades for a course will have submissions from multiple users returned. A user who can only submit will have only their own submissions returned. When a user has an in-progress submission, only that submission is returned. When there isn’t an in-progress quiz_submission, all completed submissions, including previous attempts, are returned.

200 OK response code is returned if the request was successful.

Request Parameters:

Parameter
Type
Description

include[]

string

Associations to include with the quiz submission.

Allowed values: submission, quiz, user

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submission

Scope: url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/submission

Get the submission for this quiz for the current user.

200 OK response code is returned if the request was successful.

Request Parameters:

Parameter
Type
Description

include[]

string

Associations to include with the quiz submission.

Allowed values: submission, quiz, user

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id

Scope: url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id

Get a single quiz submission.

200 OK response code is returned if the request was successful.

Request Parameters:

Parameter
Type
Description

include[]

string

Associations to include with the quiz submission.

Allowed values: submission, quiz, user

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

POST /api/v1/courses/:course_id/quizzes/:quiz_id/submissions

Scope: url:POST|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions

Start taking a Quiz by creating a QuizSubmission which you can use to answer questions and submit your answers.

Responses

  • 200 OK if the request was successful

  • 400 Bad Request if the quiz is locked

  • 403 Forbidden if an invalid access code is specified

  • 403 Forbidden if the Quiz’s IP filter restriction does not pass

  • 409 Conflict if a QuizSubmission already exists for this user and quiz

Request Parameters:

Parameter
Type
Description

access_code

string

Access code for the Quiz, if any.

preview

boolean

Whether this should be a preview QuizSubmission and not count towards the user’s course record. Teachers only.

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

PUT /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id

Scope: url:PUT|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id

Update the amount of points a student has scored for questions they’ve answered, provide comments for the student about their answer(s), or simply fudge the total score by a specific amount of points.

Responses

  • 200 OK if the request was successful

  • 403 Forbidden if you are not a teacher in this course

  • 400 Bad Request if the attempt parameter is missing or invalid

  • 400 Bad Request if the specified QS attempt is not yet complete

Request Parameters:

Parameter
Type
Description

quiz_submissions[][attempt]

Required integer

The attempt number of the quiz submission that should be updated. This attempt MUST be already completed.

quiz_submissions[][fudge_points]

number

Amount of positive or negative points to fudge the total score by.

quiz_submissions[][questions]

Hash

Example Request:

{
  "quiz_submissions": [{
    "attempt": 1,
    "fudge_points": -2.4,
    "questions": {
      "1": {
        "score": 2.5,
        "comment": "This can't be right, but I'll let it pass this one time."
      },
      "2": {
        "score": 0,
        "comment": "Good thinking. Almost!"
      }
    }
  }]
}

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

See Also:

POST /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id/complete

Scope: url:POST|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id/complete

Complete the quiz submission by marking it as complete and grading it. When the quiz submission has been marked as complete, no further modifications will be allowed.

Responses

  • 200 OK if the request was successful

  • 403 Forbidden if an invalid access code is specified

  • 403 Forbidden if the Quiz’s IP filter restriction does not pass

  • 403 Forbidden if an invalid token is specified

  • 400 Bad Request if the QS is already complete

  • 400 Bad Request if the attempt parameter is missing

  • 400 Bad Request if the attempt parameter is not the latest attempt

Request Parameters:

Parameter
Type
Description

attempt

Required integer

The attempt number of the quiz submission that should be completed. Note that this must be the latest attempt index, as earlier attempts can not be modified.

validation_token

Required string

The unique validation token you received when this Quiz Submission was created.

access_code

string

Access code for the Quiz, if any.

Example Response:

{
  "quiz_submissions": [QuizSubmission]
}

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id/time

Scope: url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id/time

Get the current timing data for the quiz attempt, both the end_at timestamp and the time_left parameter.

Responses

  • 200 OK if the request was successful

Example Response:

{
  "end_at": [DateTime],
  "time_left": [Integer]
}

Appendixes

Appendix: Manual Scoring

Parameter synopsis

{
  "quiz_submissions": [{
    "fudge_points": null, // null for no change, or a signed decimal
    "questions": {
      "QUESTION_ID": {
        "score": null, // null for no change, or an unsigned decimal
        "comment": null // null for no change, '' for no comment, or a string
      }
    }
  }]
}

More example requests

Fudging the score by a negative amount

{
  "quiz_submissions": [{
    "attempt": 1,
    "fudge_points": -2.4
  }]
}

Removing an earlier comment on a question

{
  "quiz_submissions": [{
    "attempt": 1,
    "questions": {
      "1": {
        "comment": ""
      }
    }
  }]
}

PreviousQuiz Submission User ListNextQuizzes

Last updated 1 month ago

Was this helpful?

A set of scores and comments for each question answered by the student. The keys are the question IDs, and the values are hashes of ‘scoreandcomment` entries. See for more on this parameter.

This documentation is generated directly from the Canvas LMS source code, available .

Quizzes::QuizSubmissionsApiController#index
Quizzes::QuizSubmissionsApiController#submission
Quizzes::QuizSubmissionsApiController#show
Quizzes::QuizSubmissionsApiController#create
Quizzes::QuizSubmissionsApiController#update
Quizzes::QuizSubmissionsApiController#complete
Quizzes::QuizSubmissionsApiController#time
on Github
Get all quiz submissions.
Get the quiz submission.
Get a single quiz submission.
Create the quiz submission (start a quiz-taking session)
Update student question scores and comments.
Appendix: Manual Scoring
Complete the quiz submission (turn it in).
Get current quiz submission times.
Appendix: Manual Scoring