# Quiz Submissions

{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}

## Quiz Submissions API

API for accessing quiz submissions

**A QuizSubmission object looks like:**

```js
{
  // 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 all quiz submissions.](#method.quizzes/quiz_submissions_api.index) <a href="#method.quizzes-quiz_submissions_api.index" id="method.quizzes-quiz_submissions_api.index"></a>

[Quizzes::QuizSubmissionsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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` | <p>Associations to include with the quiz submission.</p><p>Allowed values: <code>submission</code>, <code>quiz</code>, <code>user</code></p> |

**Example Response:**

```js
{
  "quiz_submissions": [QuizSubmission]
}
```

### [Get the quiz submission.](#method.quizzes/quiz_submissions_api.submission) <a href="#method.quizzes-quiz_submissions_api.submission" id="method.quizzes-quiz_submissions_api.submission"></a>

[Quizzes::QuizSubmissionsApiController#submission](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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` | <p>Associations to include with the quiz submission.</p><p>Allowed values: <code>submission</code>, <code>quiz</code>, <code>user</code></p> |

**Example Response:**

```js
{
  "quiz_submissions": [QuizSubmission]
}
```

### [Get a single quiz submission.](#method.quizzes/quiz_submissions_api.show) <a href="#method.quizzes-quiz_submissions_api.show" id="method.quizzes-quiz_submissions_api.show"></a>

[Quizzes::QuizSubmissionsApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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` | <p>Associations to include with the quiz submission.</p><p>Allowed values: <code>submission</code>, <code>quiz</code>, <code>user</code></p> |

**Example Response:**

```js
{
  "quiz_submissions": [QuizSubmission]
}
```

### [Create the quiz submission (start a quiz-taking session)](#method.quizzes/quiz_submissions_api.create) <a href="#method.quizzes-quiz_submissions_api.create" id="method.quizzes-quiz_submissions_api.create"></a>

[Quizzes::QuizSubmissionsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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:**

```js
{
  "quiz_submissions": [QuizSubmission]
}
```

### [Update student question scores and comments.](#method.quizzes/quiz_submissions_api.update) <a href="#method.quizzes-quiz_submissions_api.update" id="method.quizzes-quiz_submissions_api.update"></a>

[Quizzes::QuizSubmissionsApiController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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`             | 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 `score` and `comment` entries. See [Appendix: Manual Scoring](#Manual+Scoring-appendix) for more on this parameter. |

**Example Request:**

```bash
{
  "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:**

```js
{
  "quiz_submissions": [QuizSubmission]
}
```

**See Also:**

* [Appendix: Manual Scoring](#Manual+Scoring-appendix)

  ### [Complete the quiz submission (turn it in).](#method.quizzes/quiz_submissions_api.complete) <a href="#method.quizzes-quiz_submissions_api.complete" id="method.quizzes-quiz_submissions_api.complete"></a>

[Quizzes::QuizSubmissionsApiController#complete](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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:**

```js
{
  "quiz_submissions": [QuizSubmission]
}
```

### [Get current quiz submission times.](#method.quizzes/quiz_submissions_api.time) <a href="#method.quizzes-quiz_submissions_api.time" id="method.quizzes-quiz_submissions_api.time"></a>

[Quizzes::QuizSubmissionsApiController#time](https://github.com/instructure/canvas-lms/blob/master/app/controllers/quizzes/quiz_submissions_api_controller.rb)

**`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:**

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

### Appendixes

#### Appendix: Manual Scoring <a href="#manualscoring-appendix" id="manualscoring-appendix"></a>

**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 <a href="#more-example-requests" id="more-example-requests"></a>

**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": ""
      }
    }
  }]
}
```

***

This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developerdocs.instructure.com/services/canvas/resources/quiz_submissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.