Documentation

GradebookHistory extends AbstractBaseApi
in package

CanvasLMS

Api

GradebookHistory

GradebookHistory Class

Provides access to the versioned history of student submissions and grade changes in Canvas LMS. This API is essential for academic integrity, grade disputes, and compliance requirements as it provides a complete audit trail of all grading activities.

The Gradebook History API tracks:

All grade changes with timestamps
Who made each grade change (grader information)
Previous and new grade values
Date-based organization of grading activities
Submission versions and their changes over time

Usage:

// Set the course context
GradebookHistory::setCourse(123);

// Get days with grading activity
$days = GradebookHistory::fetchDays();

// Get details for a specific day
$graders = GradebookHistory::fetchDay('2025-01-15');

// Get detailed submissions for a specific grader, assignment, and date
$submissions = GradebookHistory::fetchSubmissions('2025-01-15', 456, 789);

// Get submission versions feed with pagination
$feed = GradebookHistory::fetchFeedPaginated([
    'assignment_id' => 789,
    'user_id' => 456,
    'ascending' => true
]);

// Access through Course instance
$course = Course::find(123);
$history = $course->gradebookHistory();
$days = $history::fetchDays();

Properties

$courseId : int|null: The course ID context for gradebook history operations
$methodAliases : array<string, array<string|int, string>>: Define method aliases

Methods

__callStatic() : mixed: Magic method to handle function aliases
__construct() : mixed: BaseApi constructor.
all() : array<string|int, static>: Get all pages of results
fetchAllFeed() : array<string|int, SubmissionVersion>: Get all submission versions from the feed (memory intensive).
fetchDay() : array<string|int, GradebookHistoryGrader>: Get details for a specific day in gradebook history.
fetchDays() : array<string|int, GradebookHistoryDay>: List days with grading activity in the course.
fetchFeed() : array<string|int, SubmissionVersion>: Get a paginated feed of submission versions.
fetchFeedPaginated() : PaginatedResponse: Get a paginated feed of submission versions with pagination support.
fetchSubmissions() : array<string|int, SubmissionHistory>: Get detailed submissions for a specific date, grader, and assignment.
find() : static: Find a specific resource by ID.
get() : array<string|int, static>: Get first page of results
getCourse() : int|null: Get the current course context.
overrideApiClient() : void: Set an API client for this class only, leaving other resources on the shared default.
paginate() : PaginationResult: Get paginated results with metadata
resetApiClients() : void: Clear the shared default client and all per-class overrides.
resetCourse() : void: Reset the course context.
setApiClient() : void: Set the shared default API client used by ALL resource classes.
setCourse() : void: Set the course context for gradebook history operations.
stream() : Generator<int, static>: Stream all items across all pages one at a time.
castValue() : DateTime|mixed: Cast a value to the correct type
checkApiClient() : void: Check if the API client is set, if not, instantiate a new one
checkCourse() : void: Check if course context is set and throw exception if not.
convertPaginatedResponseToModels() : array<string|int, static>: Helper method to convert paginated response data to model instances
createConfiguredHttpClient() : HttpClient: Create an HttpClient with configured middleware
createPaginationResult() : PaginationResult: Helper method to create PaginationResult from paginated response
getAliasMap() : array<string, string>: Build a flat alias-to-method lookup from $methodAliases.
getApiClient() : HttpClientInterface: Get the API client, initializing if necessary
getApiEndpoint() : string: Get the API endpoint name for this resource.
getEndpoint() : string: Get the base endpoint for gradebook history operations.
getPaginatedResponse() : PaginatedResponse: Helper method to get paginated response from API endpoint
hydrate() : void: Assign API response data to properties with type coercion.
parseJsonResponse() : array<string|int, mixed>: Parse JSON response from API safely handling StreamInterface
populate() : void: Populate the object with new data
toDtoArray() : array<string|int, mixed>: Convert the object to an array
validateContext() : void: Validate a context type path segment against an allowlist.

$courseId

The course ID context for gradebook history operations


        protected
        static    int|null
    $courseId
     = null

$methodAliases

Define method aliases


        protected
        static    array<string, array<string|int, string>>
    $methodAliases
     = ['get' => ['fetch', 'list'], 'all' => ['fetchAllPages', 'getAll', 'fetchAll'], 'paginate' => ['getPaginated', 'withPagination'], 'find' => ['one', 'getOne']]

__callStatic()

Magic method to handle function aliases


    public
            static        __callStatic(string $name, array<string|int, mixed> $arguments) : mixed

Parameters

$name : string
$arguments : array<string|int, mixed>

__construct()

BaseApi constructor.


    public
                    __construct(array<string|int, mixed> $data) : mixed

Parameters

$data : array<string|int, mixed>

all()

Get all pages of results


    public
            static        all([array<string, mixed> $params = [] ]) : array<string|int, static>

Parameters

$params : array<string, mixed> = []: Query parameters

Return values

array<string|int, static>

fetchAllFeed()

Get all submission versions from the feed (memory intensive).


    public
            static        fetchAllFeed([array<string, mixed> $params = [] ]) : array<string|int, SubmissionVersion>

This method fetches all pages of submission versions. Use with caution on large datasets as it loads all results into memory.

Parameters

$params : array<string, mixed> = []: Optional query parameters

Return values

array<string|int, SubmissionVersion>

fetchDay()

Get details for a specific day in gradebook history.


    public
            static        fetchDay(string $date[, array<string, mixed> $params = [] ]) : array<string|int, GradebookHistoryGrader>

Returns the graders who worked on this day, along with the assignments they worked on. More details can be obtained by calling fetchSubmissions() with a specific grader and assignment.

Parameters

$date : string: The date in YYYY-MM-DD format
$params : array<string, mixed> = []: Optional query parameters

Return values

array<string|int, GradebookHistoryGrader>

fetchDays()

List days with grading activity in the course.


    public
            static        fetchDays([array<string, mixed> $params = [] ]) : array<string|int, GradebookHistoryDay>

Returns a list of dates that have grading activity in this course. The response is ordered by date, descending (newest first).

Parameters

$params : array<string, mixed> = []: Optional query parameters

Return values

array<string|int, GradebookHistoryDay>

fetchFeed()

Get a paginated feed of submission versions.


    public
            static        fetchFeed([array<string, mixed> $params = [] ]) : array<string|int, SubmissionVersion>

Returns a paginated, uncollated list of submission versions for all matching submissions in the course. The SubmissionVersion objects returned by this endpoint will not include the new_grade or previous_grade keys, only the grade; same for graded_at and grader.

Parameters

$params : array<string, mixed> = []

Optional query parameters:

assignment_id (int): Filter by assignment ID
user_id (int): Filter by user ID
ascending (bool): Return in ascending date order (oldest first)

Return values

array<string|int, SubmissionVersion>

fetchFeedPaginated()

Get a paginated feed of submission versions with pagination support.


    public
            static        fetchFeedPaginated([array<string, mixed> $params = [] ]) : PaginatedResponse

Returns a PaginatedResponse containing submission versions and pagination metadata. This is useful for processing large datasets efficiently.

Parameters

$params : array<string, mixed> = []

Optional query parameters:

assignment_id (int): Filter by assignment ID
user_id (int): Filter by user ID
ascending (bool): Return in ascending date order (oldest first)
per_page (int): Number of items per page (default: 10, max: 100)

Return values

PaginatedResponse

fetchSubmissions()

Get detailed submissions for a specific date, grader, and assignment.


    public
            static        fetchSubmissions(string $date, int $graderId, int $assignmentId[, array<string, mixed> $params = [] ]) : array<string|int, SubmissionHistory>

Returns a nested list of submission versions for all submissions graded by the specified grader for the specified assignment on the specified date.

Parameters

$date : string: The date in YYYY-MM-DD format
$graderId : int: The ID of the grader
$assignmentId : int: The ID of the assignment
$params : array<string, mixed> = []: Optional query parameters

Return values

array<string|int, SubmissionHistory>

find()

Find a specific resource by ID.


    public
            static        find(int $id[, array<string|int, mixed> $params = [] ]) : static

Note: Gradebook History API doesn't support finding individual records by ID. This method is required by the interface but not applicable for this resource.

Parameters

$id : int: The ID to search for
$params : array<string|int, mixed> = []: Optional query parameters

Return values

static

get()

Get first page of results


    public
            static        get([array<string, mixed> $params = [] ]) : array<string|int, static>

Parameters

$params : array<string, mixed> = []: Query parameters

Return values

array<string|int, static>

getCourse()

Get the current course context.


    public
            static        getCourse() : int|null

Return values

int|null

overrideApiClient()

Set an API client for this class only, leaving other resources on the shared default.


    public
            static        overrideApiClient(HttpClientInterface $apiClient) : void

Parameters

$apiClient : HttpClientInterface

paginate()

Get paginated results with metadata


    public
            static        paginate([array<string, mixed> $params = [] ]) : PaginationResult

Parameters

$params : array<string, mixed> = []: Query parameters

Return values

PaginationResult

resetApiClients()

Clear the shared default client and all per-class overrides.


    public
            static        resetApiClients() : void

resetCourse()

Reset the course context.


    public
            static        resetCourse() : void

setApiClient()

Set the shared default API client used by ALL resource classes.


    public
            static        setApiClient(HttpClientInterface $apiClient) : void

Calling this on any resource (e.g. Course::setApiClient()) replaces the client for every resource, because relationship methods cross class boundaries ($course->enrollments() calls Enrollment internally). Use overrideApiClient() to scope a client to a single class, and resetApiClients() in test teardown to avoid state leaking.

Parameters

$apiClient : HttpClientInterface

setCourse()

Set the course context for gradebook history operations.


    public
            static        setCourse(int $courseId) : void

Parameters

$courseId : int: The ID of the course

stream()

Stream all items across all pages one at a time.


    public
            static        stream([array<string|int, mixed> $params = [] ]) : Generator<int, static>

Unlike all(), only one page of raw data is held in memory at a time, making this safe for very large datasets (e.g. tens of thousands of enrollments):

foreach (User::stream(['per_page' => 100]) as $user) {
    processUser($user);
}

Parameters

$params : array<string|int, mixed> = []: Query parameters for the request

Return values

Generator<int, static>

castValue()

Cast a value to the correct type


    protected
                    castValue(string $key, mixed $value) : DateTime|mixed

Parameters

$key : string
$value : mixed

Return values

DateTime|mixed

checkApiClient()

Check if the API client is set, if not, instantiate a new one


    protected
            static        checkApiClient() : void

checkCourse()

Check if course context is set and throw exception if not.


    protected
            static        checkCourse() : void

convertPaginatedResponseToModels()

Helper method to convert paginated response data to model instances


    protected
            static        convertPaginatedResponseToModels(PaginatedResponse $paginatedResponse) : array<string|int, static>

Parameters

$paginatedResponse : PaginatedResponse

Return values

array<string|int, static>

createConfiguredHttpClient()

Create an HttpClient with configured middleware


    protected
            static        createConfiguredHttpClient() : HttpClient

Return values

HttpClient

createPaginationResult()

Helper method to create PaginationResult from paginated response


    protected
            static        createPaginationResult(PaginatedResponse $paginatedResponse) : PaginationResult

Parameters

$paginatedResponse : PaginatedResponse

Return values

PaginationResult

getAliasMap()

Build a flat alias-to-method lookup from $methodAliases.


    protected
            static        getAliasMap() : array<string, string>

Return values

array<string, string>

getApiClient()

Get the API client, initializing if necessary


    protected
            static        getApiClient() : HttpClientInterface

Return values

HttpClientInterface

getApiEndpoint()

Get the API endpoint name for this resource.


    protected
            static        getApiEndpoint() : string

Return values

string

getEndpoint()

Get the base endpoint for gradebook history operations.


    protected
            static        getEndpoint() : string

Return values

string

getPaginatedResponse()

Helper method to get paginated response from API endpoint


    protected
            static        getPaginatedResponse(string $endpoint[, array<string|int, mixed> $params = [] ]) : PaginatedResponse

Parameters

$endpoint : string: The API endpoint path
$params : array<string|int, mixed> = []: Query parameters for the request

Return values

PaginatedResponse

hydrate()

Assign API response data to properties with type coercion.


    protected
                    hydrate(array<string|int, mixed> $data) : void

Shared by the constructor and populate() so objects keep the same type guarantees after save()/update() round-trips as on creation.

Parameters

$data : array<string|int, mixed>

parseJsonResponse()

Parse JSON response from API safely handling StreamInterface


    protected
            static        parseJsonResponse(ResponseInterface $response) : array<string|int, mixed>

Parameters

$response : ResponseInterface

Return values

array<string|int, mixed>

populate()

Populate the object with new data


    protected
                    populate(array<string|int, mixed> $data) : void

Parameters

$data : array<string|int, mixed>

toDtoArray()

Convert the object to an array


    protected
                    toDtoArray() : array<string|int, mixed>

Return values

array<string|int, mixed>

validateContext()

Validate a context type path segment against an allowlist.


    protected
            static        validateContext(string|null $contextType, array<int, string> $allowed) : void

Context types are interpolated into URL paths; validating against the contexts Canvas actually supports prevents crafted values from injecting extra path segments or query parameters.

Parameters

$contextType : string|null: The context type (plural, e.g. 'courses'); null is ignored
$allowed : array<int, string>: Allowed context types

GradebookHistory extends AbstractBaseApi in package CanvasLMS Api GradebookHistory

Tags

Table of Contents

Properties

Methods

Properties

$courseId

$methodAliases

Methods

__callStatic()

Parameters

Tags

__construct()

Parameters

all()

Parameters

Return values

fetchAllFeed()

Parameters

Tags

Return values

fetchDay()

Parameters

Tags

Return values

fetchDays()

Parameters

Tags

Return values

fetchFeed()

Parameters

Tags

Return values

fetchFeedPaginated()

Parameters

Tags

Return values

fetchSubmissions()

Parameters

Tags

Return values

find()

Parameters

Tags

Return values

get()

Parameters

Return values

getCourse()

Return values

overrideApiClient()

Parameters

paginate()

Parameters

Return values

resetApiClients()

resetCourse()

setApiClient()

Parameters

setCourse()

Parameters

stream()

Parameters

Tags

Return values

castValue()

Parameters

Tags

Return values

checkApiClient()

checkCourse()

Tags

convertPaginatedResponseToModels()

Parameters

Return values

createConfiguredHttpClient()

Return values

createPaginationResult()

Parameters

Return values

GradebookHistory extends AbstractBaseApi
in package

CanvasLMS

Api

GradebookHistory