Skip to content
Schoology Dev Docs

Grade/Grades

Grades are associated with an enrollment and an assignment. Grades are point values assigned to users for a specific assignment through enrollments.

Fields

Section titled “Fields”
Field Name Description Type
enrollment_id Enrollment ID The ID of the enrollment for which you are assigning a grade / to which the grade belongs. integer
assignment_id Assignment ID The ID of the assignment for which you are assigning a grade / to which the grade belongs. integer or string
section_id Section ID The ID of the course section to which the enrollment belongs. integer
grade Grade The grade you are assigning the enrollment/assignment combination. Assignments with an assigned grading scale can accept letter-grades as defined by the scale — these will be converted to numeric values upon save. integer or string
exception Exception An exception represents an exception to the grade item associated with this grade. If exception > 0 then grade will be set to NULL. Current exceptions: 1 = excused, 2 = incomplete. integer
comment Comment A comment to associate with this grade. string
comment_status Comment status Whether or not the grade comment is visible to the student. Only administrators will see this value. Values: {1,0}. integer
timestamp Timestamp The Unix timestamp the last time the grade was updated in any way, according to server time. integer or string
is_final Is Final Whether the grade object belongs to a midterm/final. Values: 0 or 1. integer
type Type The type of grade item this grade refers to. Values: assignment, discussion. string
location API location Points to an API endpoint where the specific content this grade refers to can be found. string
max_points Max Points The maximum points possible for the assignment. integer
scale_id Scale ID The ID of the grading scale used. integer
scale_type Scale Type The type of grading scale. integer
category_id Category ID The ID of the grading category. integer

GET sections/{section id}/grades

Section titled “GET sections/{section id}/grades”

View a list of grades (paged). Optional query parameters: assignment_id, enrollment_id, timestamp. Retrieving this list without specifying the above parameters will return a paged list of all grades for all assignments and students in the course section.

Query parameters:

  • assignment_id (optional)
  • enrollment_id (optional)
  • timestamp (optional)

Return A list of grade objects

{
  "grades": {
    "grade": [
      {
        "enrollment_id": 44783151,
        "assignment_id": 5699937,
        "grade": 80,
        "exception": 0,
        "max_points": 100,
        "is_final": 0,
        "timestamp": 1389651403,
        "comment": "",
        "comment_status": null,
        "override": null,
        "calculated_grade": null,
        "pending": null,
        "type": "assignment",
        "location": "http:\/\/...\/5699937",
        "scale_id": 1,
        "scale_type": 0,
        "category_id": 4341
      }
    ]
  },
  "period": [
    {
      "period_id": "p13011",
      "period_title": "Never Ending Period",
      "weight": "100.00"
    }
  ],
  "final_grade": [
    {
      "enrollment_id": "44783151",
      "period": [
        {
          "period_id": "p13011",
          "grade": 80,
          "comment": "",
          "comment_status": null
        },
        {
          "period_id": "other",
          "grade": null,
          "comment": "",
          "comment_status": null
        },
        {
          "period_id": "final",
          "grade": 80,
          "comment": "",
          "comment_status": null
        }
      ],
      "scale_id": 0
    }
  ]
}

PUT sections/{section id}/grades

Section titled “PUT sections/{section id}/grades”

Set/modify grades.

Content Objects containing grade fields (enrollment_id, assignment_id, grade, optionally comment, exception, etc.)

{
  "grades": {
    "grade": [
      {
        "type": "assignment",
        "assignment_id": 5007606,
        "enrollment_id": "44783136",
        "grade": 99,
        "comment": "grade submmitted"
      },
      {
        "type": "assignment",
        "assignment_id": 5007606,
        "enrollment_id": "44783141",
        "grade": 76,
        "comment": "grade submmitted"
      }
    ]
  }
}

PUT sections/{section id}/grades (final comments)

Section titled “PUT sections/{section id}/grades (final comments)”

Set/modify comments for students for a grading period and the overall course.

Content Objects containing final comments fields. Parameters:

  • enrollment_id (required)
  • period_id (required) — which grading period to post the comment for; passing "final" posts the comment to the final grade for the course
  • comment (required)
  • comment_status (optional) — whether the comment is visible to the student (1 or 0, default 0)
{
  "final_comments": {
    "final_comment": [
      {
        "enrollment_id": "24152019",
        "period_id": "26127",
        "comment": "Great improvement from first semester!",
        "comment_status": "1"
      },
      {
        "enrollment_id": "24152019",
        "period_id": "final",
        "comment": "Overall tremendous improvement",
        "comment_status": "1"
      }
    ]
  }
}

GET users/{user id}/grades

Section titled “GET users/{user id}/grades”

View a list of grades in the active enrollments for the given user. The following query strings can (optionally) be appended to the path to filter results:

Query parameters:

  • section_id (optional) — Specifying a section id limits results to that section. Note: Some implementations may require this parameter and return a 403 Forbidden error if not provided.
  • grading_period_ids (optional) — Specifying a comma-delimited list of grading period ids limits results to those grading periods. Use other for the “Other” grading period, and final for final grades.
  • timestamp (optional) — Specifying a timestamp limits results to recorded grades that have been updated since the given timestamp, according to the server time.
  • include_all_enrollments (optional) — If set to 1, grades for all enrollments including inactive will be included in the response.

Note: The output when using timestamp or include_all_enrollments is paginated by enrollment and will include a links object with a next key to navigate to the next page of enrollment grades.

Return A list of grades grouped by section

{
  "section": [
    {
      "section_id": "4318461",
      "period": [
        {
          "period_id": "p13011",
          "period_title": "Never Ending Period",
          "assignment": [
            {
              "enrollment_id": 44783151,
              "assignment_id": 5699937,
              "grade": 80,
              "exception": 0,
              "max_points": 100,
              "is_final": 0,
              "timestamp": 1389651403,
              "comment": "",
              "comment_status": null,
              "override": null,
              "calculated_grade": null,
              "pending": null,
              "type": "assignment",
              "location": "http:\/\/...\/5699937",
              "scale_id": 1,
              "scale_type": 0,
              "category_id": 4341
            }
          ]
        }
      ],
      "final_grade": [
        {
          "period_id": "p13011",
          "grade": 80,
          "weight": 100,
          "comment": "",
          "scale_id": 0,
          "grading_category": [
            {
              "category_id": 3081,
              "grade": null
            },
            {
              "category_id": 4341,
              "grade": 80
            }
          ],
          "comment_status": null
        },
        {
          "period_id": "final",
          "grade": 80,
          "comment": "",
          "comment_status": null,
          "scale_id": 0
        }
      ],
      "grading_category": [
        {
          "id": 3081,
          "title": "e.g. Homework"
        },
        {
          "id": 4341,
          "title": "xtra points"
        }
      ]
    }
  ],
  "links": {
    "self": "http:\/\/...\/v1\/users\/48289\/grades"
  }
}