🚀 Heads up: Our API Docs Have Moved!
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.

What If Grades API

A Grade object looks like:

{
  // The grade for the course
  "grade": 120.0,
  // The total points earned in the course
  "total": 24.0,
  // The total points possible for the course
  "possible": 20.0,
  // The dropped grades for the course
  "dropped": []
}

An AssignmentGroupGrade object looks like:

{
  // The ID of the Assignment Group
  "id": 123,
  // The global ID of the Assignment Group
  "global_id": 10000000000001,
  // The score for the Assignment Group
  "score": 20.0,
  // The total points possible for the Assignment Group
  "possible": 10.0,
  // The weight for the Assignment Group
  "weight": 0.0,
  // The grade for the Assignment Group
  "grade": 200.0,
  // The dropped grades for the Assignment Group
  "dropped": []
}

A GradeGroup object looks like:

{
  "submission_id": null
}

A Grades object looks like:

{
  "current": null,
  "current_groups": null,
  "final": null,
  "final_groups": null
}

A Submission object looks like:

{
  // The ID of the submission
  "id": 123,
  // The score the student wants to test
  "student_entered_score": "20.0"
}

Update a submission's what-if score and calculate grades WhatIfGradesApiController#update

PUT /api/v1/submissions/:id/what_if_grades

Scope: url:PUT|/api/v1/submissions/:id/what_if_grades

GET /courses/:course_id/files/:file_id/download

Scope: url:GET|/courses/:course_id/files/:file_id/download

GET /courses/:course_id/files/:file_id/download.:type

Scope: url:GET|/courses/:course_id/files/:file_id/download

GET /courses/:course_id/files/:file_id/preview

Scope: url:GET|/courses/:course_id/files/:file_id/preview

GET /quiz_statistics/:quiz_statistics_id/files/:file_id/download

Scope: url:GET|/quiz_statistics/:quiz_statistics_id/files/:file_id/download

GET /assessment_questions/:assessment_question_id/files/:file_id/download

Scope: url:GET|/assessment_questions/:assessment_question_id/files/:file_id/download

GET /assessment_questions/:assessment_question_id/files/:file_id/download.:type

Scope: url:GET|/assessment_questions/:assessment_question_id/files/:file_id/download

GET /assessment_questions/:assessment_question_id/files/:file_id/preview

Scope: url:GET|/assessment_questions/:assessment_question_id/files/:file_id/preview

GET /groups/:group_id/files/:file_id/download

Scope: url:GET|/groups/:group_id/files/:file_id/download

GET /groups/:group_id/files/:file_id/download.:type

Scope: url:GET|/groups/:group_id/files/:file_id/download

GET /groups/:group_id/files/:file_id/preview

Scope: url:GET|/groups/:group_id/files/:file_id/preview

GET /accounts/:account_id/files/:file_id/download

Scope: url:GET|/accounts/:account_id/files/:file_id/download

GET /accounts/:account_id/files/:file_id/download.:type

Scope: url:GET|/accounts/:account_id/files/:file_id/download

GET /accounts/:account_id/files/:file_id/preview

Scope: url:GET|/accounts/:account_id/files/:file_id/preview

GET /users/:user_id/files/:file_id/download

Scope: url:GET|/users/:user_id/files/:file_id/download

GET /users/:user_id/files/:file_id/download.:type

Scope: url:GET|/users/:user_id/files/:file_id/download

GET /users/:user_id/files/:file_id/preview

Scope: url:GET|/users/:user_id/files/:file_id/preview

GET /assignments/:assignment_id/files/:id/download

Scope: url:GET|/assignments/:assignment_id/files/:id/download

GET /files/:file_id/download

Scope: url:GET|/files/:file_id/download

GET /quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download

Scope: url:GET|/quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download

GET /quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download.:type

Scope: url:GET|/quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download

GET /quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/preview

Scope: url:GET|/quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/preview

Enter a what if score for a submission and receive the calculated grades Grade calculation is a costly operation, so this API should be used sparingly

Request Parameters:

Parameter		Type	Description
student_entered_score		number	The score the student wants to test

Example Response:

{
    "grades": [
        {
            "current": {
                "grade": 120.0,
                "total": 24.0,
                "possible": 20.0,
                "dropped": []
            },
            "current_groups": {
                "1": {
                    "id": 1,
                    "global_id": 10000000000001,
                    "score": 20.0,
                    "possible": 10.0,
                    "weight": 0.0,
                    "grade": 200.0,
                    "dropped": []
                },
                "3": {
                    "id": 3,
                    "global_id": 10000000000003,
                    "score": 4.0,
                    "possible": 10.0,
                    "weight": 0.0,
                    "grade": 40.0,
                    "dropped": []
                }
            },
            "final": {
                "grade": 21.82,
                "total": 24.0,
                "possible": 110.0,
                "dropped": []
            },
            "final_groups": {
                "1": {
                    "id": 1,
                    "global_id": 10000000000001,
                    "score": 20.0,
                    "possible": 100.0,
                    "weight": 0.0,
                    "grade": 20.0,
                    "dropped": []
                },
                "3": {
                    "id": 3,
                    "global_id": 10000000000003,
                    "score": 4.0,
                    "possible": 10.0,
                    "weight": 0.0,
                    "grade": 40.0,
                    "dropped": []
                }
            }
        }
    ],
    "submission": {
        "id": 166,
        "student_entered_score": 20.0
    }
}

Returns a list of Grades objects

Reset the what-if scores for the current user for an entire course and recalculate grades WhatIfGradesApiController#reset_for_student_course

PUT /api/v1/courses/:course_id/what_if_grades/reset

Scope: url:PUT|/api/v1/courses/:course_id/what_if_grades/reset

GET /courses/:course_id/files/:file_id/download

Scope: url:GET|/courses/:course_id/files/:file_id/download

GET /courses/:course_id/files/:file_id/download.:type

Scope: url:GET|/courses/:course_id/files/:file_id/download

GET /courses/:course_id/files/:file_id/preview

Scope: url:GET|/courses/:course_id/files/:file_id/preview

GET /quiz_statistics/:quiz_statistics_id/files/:file_id/download

Scope: url:GET|/quiz_statistics/:quiz_statistics_id/files/:file_id/download

GET /assessment_questions/:assessment_question_id/files/:file_id/download

Scope: url:GET|/assessment_questions/:assessment_question_id/files/:file_id/download

GET /assessment_questions/:assessment_question_id/files/:file_id/download.:type

Scope: url:GET|/assessment_questions/:assessment_question_id/files/:file_id/download

GET /assessment_questions/:assessment_question_id/files/:file_id/preview

Scope: url:GET|/assessment_questions/:assessment_question_id/files/:file_id/preview

GET /groups/:group_id/files/:file_id/download

Scope: url:GET|/groups/:group_id/files/:file_id/download

GET /groups/:group_id/files/:file_id/download.:type

Scope: url:GET|/groups/:group_id/files/:file_id/download

GET /groups/:group_id/files/:file_id/preview

Scope: url:GET|/groups/:group_id/files/:file_id/preview

GET /accounts/:account_id/files/:file_id/download

Scope: url:GET|/accounts/:account_id/files/:file_id/download

GET /accounts/:account_id/files/:file_id/download.:type

Scope: url:GET|/accounts/:account_id/files/:file_id/download

GET /accounts/:account_id/files/:file_id/preview

Scope: url:GET|/accounts/:account_id/files/:file_id/preview

GET /users/:user_id/files/:file_id/download

Scope: url:GET|/users/:user_id/files/:file_id/download

GET /users/:user_id/files/:file_id/download.:type

Scope: url:GET|/users/:user_id/files/:file_id/download

GET /users/:user_id/files/:file_id/preview

Scope: url:GET|/users/:user_id/files/:file_id/preview

GET /assignments/:assignment_id/files/:id/download

Scope: url:GET|/assignments/:assignment_id/files/:id/download

GET /files/:file_id/download

Scope: url:GET|/files/:file_id/download

GET /quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download

Scope: url:GET|/quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download

GET /quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download.:type

Scope: url:GET|/quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/download

GET /quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/preview

Scope: url:GET|/quizzes/quiz_submissions/:quiz_submission_id/files/:file_id/preview

Resets all what-if scores for a student in a course and recalculates grades.

Returns a list of Grades objects