Canvas

Canvas Grading Periods API

The Grading Periods API from Canvas — 6 operation(s) for grading periods.

GitHub OpenAPI

Operations 8

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v1/accounts/{account_id}/grading_periods List an account's grading periods · List grading periods #
Ask an LLM
“What grading periods are defined at the account level?”
“Which terms or quarters has my institution set up as grading periods?”
Tell an agent
List the grading periods for account {account_id}.
Show account {account_id}'s marking periods.
GET /v1/courses/{course_id}/grading_periods List a course's grading periods · List grading periods #
Ask an LLM
“What grading periods apply to my course?”
“Which quarters is my course's grade broken into?”
Tell an agent
List the grading periods for course {course_id}.
Show course {course_id}'s marking periods.
GET /v1/courses/{course_id}/grading_periods/{id} Get one grading period in a course · Get a single grading period #
Ask an LLM
“When does a specific grading period start and end?”
“Can I look up one of my course's grading periods by ID?”
Tell an agent
Get grading period {id} in course {course_id}.
Show the dates for course {course_id} grading period {id}.
PUT /v1/courses/{course_id}/grading_periods/{id} Change one grading period's dates · Update a single grading period #
Ask an LLM
“How do I move the end date of a single grading period?”
“Can I change the weight of one grading period in my course?”
Tell an agent
Set course {course_id} grading period {id} to run from {start_date} to {end_date}.
Update grading period {id} in course {course_id}: start {start_date}, end {end_date}, weight {weight}.
DELETE /v1/courses/{course_id}/grading_periods/{id} Delete a course grading period · Delete a grading period #
Ask an LLM
“How do I remove a grading period from my course?”
“Can I delete a course-level grading period I no longer need?”
Tell an agent destructive · confirm first
Delete grading period {id} from course {course_id}.
Remove course {course_id}'s grading period {id}.
DELETE /v1/accounts/{account_id}/grading_periods/{id} Delete an account grading period · Delete a grading period #
Ask an LLM
“How do I delete a grading period defined for the whole account?”
“Can an admin remove an account-level grading period?”
Tell an agent destructive · confirm first
Delete grading period {id} from account {account_id}.
Remove account {account_id}'s grading period {id}.
PATCH /v1/courses/{course_id}/grading_periods/batch_update Update several grading periods in a course · Batch update grading periods #
Ask an LLM
“How do I set up all my course's grading periods in one request?”
“Can I update titles, dates and close dates for multiple course grading periods at once?”
Tell an agent
Batch update grading periods in course {course_id} for set {set_id}.
In course {course_id}, add period {title} from {start_date} to {end_date} closing {close_date} in set {set_id}.
PATCH /v1/grading_period_sets/{set_id}/grading_periods/batch_update Update several grading periods in a set · Batch update grading periods #
Ask an LLM
“How do I edit every period in a grading period set together?”
“Can I bulk-change dates on a term's grading period set?”
Tell an agent
Batch update the grading periods in set {set_id}.
In grading period set {set_id}, add {title} from {start_date} to {end_date} closing {close_date}.

Documentation

📖
Documentation
https://canvas.instructure.com/doc/api/
📖
Authentication
https://canvas.instructure.com/doc/api/file.oauth.html
📖
APIReference
https://canvas.instructure.com/doc/api/
📖
RateLimits
https://artifacts.apis.io/canvas/rate-limits/canvas-rate-limits.yml

Specifications

⚙
OpenAPI
https://artifacts.apis.io/canvas/openapi/canvas-grading-periods-api-openapi.yml

SDKs

📦
GitHubRepository
https://github.com/instructure/canvas-lms

Other Resources

🔗
Pagination
https://canvas.instructure.com/doc/api/file.pagination.html
🔗
Swagger
https://canvas.instructure.com/doc/api/api-docs.json
🔗
OAuthScopes
https://artifacts.apis.io/canvas/scopes/canvas-scopes.yml
🔗
ErrorCatalog
https://artifacts.apis.io/canvas/errors/canvas-problem-types.yml
🔗
DataModel
https://artifacts.apis.io/canvas/data-model/canvas-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/canvas:canvas-grading-periods-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

canvas-grading-periods-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Canvas LMS REST Grading Periods API
  version: v1
  summary: The complete Canvas LMS REST API, converted from the Swagger 1.2 documents Instructure publishes under https://canvas.instructure.com/doc/api/.
  description: The Canvas LMS REST API covers courses, assignments, quizzes, grades, users, enrollments, accounts, files, modules, rubrics, submissions, SIS imports, LTI, analytics and account administration.
  contact:
    name: Instructure Canvas
    url: https://canvas.instructure.com/doc/api/
  license:
    name: AGPL-3.0
    url: https://github.com/instructure/canvas-lms/blob/master/LICENSE
servers:
- url: https://canvas.instructure.com/api
  description: Instructure-hosted Canvas (canvas.instructure.com)
- url: https://{canvas_host}/api
  description: Any Canvas instance; Canvas is multi-tenant and self-hostable, so the host is the institution's Canvas domain.
  variables:
    canvas_host:
      default: canvas.instructure.com
      description: Your institution's Canvas hostname, e.g. school.instructure.com
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Grading Periods
  x-resource: grading_periods
  externalDocs:
    url: https://canvas.instructure.com/doc/api/grading_periods.html
paths:
  /v1/accounts/{account_id}/grading_periods:
    get:
      tags:
      - Grading Periods
      operationId: list_grading_periods_accounts
      summary: List grading periods
      description: Returns the paginated list of grading periods for the current course.
      parameters:
      - name: account_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
  /v1/courses/{course_id}/grading_periods:
    get:
      tags:
      - Grading Periods
      operationId: list_grading_periods_courses
      summary: List grading periods
      description: Returns the paginated list of grading periods for the current course.
      parameters:
      - name: course_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
  /v1/courses/{course_id}/grading_periods/{id}:
    get:
      tags:
      - Grading Periods
      operationId: get_single_grading_period
      summary: Get a single grading period
      description: Returns the grading period with the given id
      parameters:
      - name: course_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      - name: id
        in: path
        schema:
          type: string
        required: true
        description: ID
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
    put:
      tags:
      - Grading Periods
      operationId: update_single_grading_period
      summary: Update a single grading period
      description: Update an existing grading period.
      parameters:
      - name: course_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      - name: id
        in: path
        schema:
          type: string
        required: true
        description: ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                grading_periods[start_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: The date the grading period starts.
                grading_periods[end_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: no description
                grading_periods[weight]:
                  type: array
                  items:
                    type: number
                  description: A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade
              required:
              - grading_periods[start_date]
              - grading_periods[end_date]
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grading_periods[start_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: The date the grading period starts.
                grading_periods[end_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: no description
                grading_periods[weight]:
                  type: array
                  items:
                    type: number
                  description: A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade
              required:
              - grading_periods[start_date]
              - grading_periods[end_date]
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
    delete:
      tags:
      - Grading Periods
      operationId: delete_grading_period_courses
      summary: Delete a grading period
      description: '204 No Content response code is returned if the deletion was

        successful.'
      parameters:
      - name: course_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      - name: id
        in: path
        schema:
          type: string
        required: true
        description: ID
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
  /v1/accounts/{account_id}/grading_periods/{id}:
    delete:
      tags:
      - Grading Periods
      operationId: delete_grading_period_accounts
      summary: Delete a grading period
      description: '204 No Content response code is returned if the deletion was

        successful.'
      parameters:
      - name: account_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      - name: id
        in: path
        schema:
          type: string
        required: true
        description: ID
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
  /v1/courses/{course_id}/grading_periods/batch_update:
    patch:
      tags:
      - Grading Periods
      operationId: batch_update_grading_periods_courses
      summary: Batch update grading periods
      description: Update multiple grading periods
      parameters:
      - name: course_id
        in: path
        schema:
          type: string
        required: true
        description: ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                set_id:
                  type: string
                  description: The id of the grading period set.
                grading_periods[id]:
                  type: array
                  items:
                    type: string
                  description: The id of the grading period. If the id parameter does not exist, a new grading period will be created.
                grading_periods[title]:
                  type: array
                  items:
                    type: string
                  description: 'The title of the grading period.

                    The title is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[start_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period starts.

                    The start_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[end_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period ends.

                    The end_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[close_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date after which grades can no longer be changed for a grading period.

                    The close_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[weight]:
                  type: array
                  items:
                    type: number
                  description: A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade
              required:
              - set_id
              - grading_periods[title]
              - grading_periods[start_date]
              - grading_periods[end_date]
              - grading_periods[close_date]
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                set_id:
                  type: string
                  description: The id of the grading period set.
                grading_periods[id]:
                  type: array
                  items:
                    type: string
                  description: The id of the grading period. If the id parameter does not exist, a new grading period will be created.
                grading_periods[title]:
                  type: array
                  items:
                    type: string
                  description: 'The title of the grading period.

                    The title is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[start_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period starts.

                    The start_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[end_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period ends.

                    The end_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[close_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date after which grades can no longer be changed for a grading period.

                    The close_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[weight]:
                  type: array
                  items:
                    type: number
                  description: A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade
              required:
              - set_id
              - grading_periods[title]
              - grading_periods[start_date]
              - grading_periods[end_date]
              - grading_periods[close_date]
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
  /v1/grading_period_sets/{set_id}/grading_periods/batch_update:
    patch:
      tags:
      - Grading Periods
      operationId: batch_update_grading_periods_grading_period_sets
      summary: Batch update grading periods
      description: Update multiple grading periods
      parameters:
      - name: set_id
        in: path
        schema:
          type: string
        required: true
        description: The id of the grading period set.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                grading_periods[id]:
                  type: array
                  items:
                    type: string
                  description: The id of the grading period. If the id parameter does not exist, a new grading period will be created.
                grading_periods[title]:
                  type: array
                  items:
                    type: string
                  description: 'The title of the grading period.

                    The title is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[start_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period starts.

                    The start_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[end_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period ends.

                    The end_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[close_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date after which grades can no longer be changed for a grading period.

                    The close_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[weight]:
                  type: array
                  items:
                    type: number
                  description: A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade
              required:
              - grading_periods[title]
              - grading_periods[start_date]
              - grading_periods[end_date]
              - grading_periods[close_date]
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grading_periods[id]:
                  type: array
                  items:
                    type: string
                  description: The id of the grading period. If the id parameter does not exist, a new grading period will be created.
                grading_periods[title]:
                  type: array
                  items:
                    type: string
                  description: 'The title of the grading period.

                    The title is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[start_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period starts.

                    The start_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[end_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date the grading period ends.

                    The end_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[close_date]:
                  type: array
                  items:
                    type: string
                    format: date
                  description: 'The date after which grades can no longer be changed for a grading period.

                    The close_date is required for creating a new grading period, but not for updating an existing grading period.'
                grading_periods[weight]:
                  type: array
                  items:
                    type: number
                  description: A weight value that contributes to the overall weight of a grading period set which is used to calculate how much assignments in this period contribute to the total grade
              required:
              - grading_periods[title]
              - grading_periods[start_date]
              - grading_periods[end_date]
              - grading_periods[close_date]
      responses:
        '200':
          description: Success, no content returned
      externalDocs:
        url: https://canvas.instructure.com/doc/api/grading_periods.html
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Canvas OAuth2 access token sent as "Authorization: Bearer <token>". See https://canvas.instructure.com/doc/api/file.oauth.html'
    oauth2:
      type: oauth2
      description: Canvas OAuth2. See https://canvas.instructure.com/doc/api/file.oauth.html and https://canvas.instructure.com/doc/api/file.oauth_endpoints.html
      flows:
        authorizationCode:
          authorizationUrl: https://canvas.instructure.com/login/oauth2/auth
          tokenUrl: https://canvas.instructure.com/login/oauth2/token
          refreshUrl: https://canvas.instructure.com/login/oauth2/token
          scopes: {}
externalDocs:
  description: Canvas LMS REST API Documentation
  url: https://canvas.instructure.com/doc/api/
x-generated-from: https://canvas.instructure.com/doc/api/api-docs.json
x-provenance:
  method: derived
  derived_by: API Evangelist enrichment pipeline (Swagger 1.2 -> OpenAPI 3.1 conversion)
  source: openapi/_original/swagger-1.2/*.json (144 verbatim first-party Swagger 1.2 documents)
  source_url: https://canvas.instructure.com/doc/api/api-docs.json
  fetched: '2026-09-05'
  http_status: 200