canvas.courses.list-users-in-course-users

Returns the paginated list of users in this course. And optionally the user's enrollments in the course.

List users in course

Overview

Property	Value
Workflow type	Atomic
Library	App-canvas
Version	1.0

Input Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Canvas API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
course_id	string	Yes	—	ID
search_term	string	No	—	The partial name or full ID of the users to match and return in the results list.
sort	string	No	—	When set, sort the results of the search based on the given field.
enrollment_type	list	No	—	When set, only return users where the user is enrolled as this type. "student_view" implies include[]=test_student. This argument is ignored if enrollment_role is given.
enrollment_role	string	No	—	Deprecated When set, only return users enrolled with the specified course-level role. This can be a role created with the {api:RoleOverridesController#add_role Add Role API} or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.
enrollment_role_id	integer	No	—	When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the {api:RoleOverridesController#add_role Add Role API} or a built_in role id with type 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.
section_ids	list	No	—	When set, only return users who are enrolled in the given section(s).
include	list	No	—	- "enrollments": Optionally include with each Course the user's current and invited enrollments. If the user is enrolled as a student, and the account has permission to manage or view all grades, each enrollment will include a 'grades' key with 'current_score', 'final_score', 'current_grade' and 'final_grade' values. - "locked": Optionally include whether an enrollment is locked. - "avatar_url": Optionally include avatar_url. - "bio": Optionally include each user's bio. - "test_student": Optionally include the course's Test Student, if present. Default is to not include Test Student. - "custom_links": Optionally include plugin-supplied custom links for each student, such as analytics information - "current_grading_period_scores": if enrollments is included as well as this directive, the scores returned in the enrollment will be for the current grading period if there is one. A 'grading_period_id' value will also be included with the scores. if grading_period_id is nil there is no current grading period and the score is a total score. - "uuid": Optionally include the users uuid
user_id	string	No	—	If this parameter is given and it corresponds to a user in the course, the +page+ parameter will be ignored and the page containing the specified user will be returned instead.
user_ids	list	No	—	If included, the course users set will only include users with IDs specified by the param. Note: this will not work in conjunction with the "user_id" argument but multiple user_ids can be included.
enrollment_state	list	No	—	When set, only return users where the enrollment workflow state is of one of the given types. "active" and "invited" enrollments are returned by default.

Output Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Canvas API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
course_id	string	Yes	—	ID
search_term	string	No	—	The partial name or full ID of the users to match and return in the results list.
sort	string	No	—	When set, sort the results of the search based on the given field.
enrollment_type	list	No	—	When set, only return users where the user is enrolled as this type. "student_view" implies include[]=test_student. This argument is ignored if enrollment_role is given.
enrollment_role	string	No	—	Deprecated When set, only return users enrolled with the specified course-level role. This can be a role created with the {api:RoleOverridesController#add_role Add Role API} or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.
enrollment_role_id	integer	No	—	When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the {api:RoleOverridesController#add_role Add Role API} or a built_in role id with type 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.
section_ids	list	No	—	When set, only return users who are enrolled in the given section(s).
include	list	No	—	- "enrollments": Optionally include with each Course the user's current and invited enrollments. If the user is enrolled as a student, and the account has permission to manage or view all grades, each enrollment will include a 'grades' key with 'current_score', 'final_score', 'current_grade' and 'final_grade' values. - "locked": Optionally include whether an enrollment is locked. - "avatar_url": Optionally include avatar_url. - "bio": Optionally include each user's bio. - "test_student": Optionally include the course's Test Student, if present. Default is to not include Test Student. - "custom_links": Optionally include plugin-supplied custom links for each student, such as analytics information - "current_grading_period_scores": if enrollments is included as well as this directive, the scores returned in the enrollment will be for the current grading period if there is one. A 'grading_period_id' value will also be included with the scores. if grading_period_id is nil there is no current grading period and the score is a total score. - "uuid": Optionally include the users uuid
user_id	string	No	—	If this parameter is given and it corresponds to a user in the course, the +page+ parameter will be ignored and the page containing the specified user will be returned instead.
user_ids	list	No	—	If included, the course users set will only include users with IDs specified by the param. Note: this will not work in conjunction with the "user_id" argument but multiple user_ids can be included.
enrollment_state	list	No	—	When set, only return users where the enrollment workflow state is of one of the given types. "active" and "invited" enrollments are returned by default.
status_code	integer	No	—	HTTP status code of the completed call
response	json	No	—	Parsed JSON response body
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_at	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
failed_at_state	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Waiting to call GET /v1/courses/{course_id}/users
completed	No	Yes	Yes	—	HTTP call succeeded
failed	No	Yes	No	—	HTTP call failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	Perform GET /v1/courses/{course_id}/users
* (any state)	fail	failed	Record the failure reason

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "canvas.courses.list-users-in-course-users",
  "initial_data": {
    "base_url": "value",
    "course_id": "value"
  }
}