🚀 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.

Cohorts API

Manage cohorts, groups of people placed in an account. Cohorts nest into trees up to a configurable depth, 10 by default.

A Cohort object looks like:

// A named group in a Canvas account.
{
  // the ID of the cohort
  "id": 4002,
  // the root account at the top of the account hierarchy the cohort is placed in
  "root_account_id": 1,
  // the root cohort of this cohort's tree; equal to id when the cohort is itself
  // a root
  "root_cohort_id": 4000,
  // the account the cohort is placed in, a root account or a sub-account
  "account_id": 1,
  // the cohort one level above this one, or null for a root cohort
  "parent_cohort_id": 4000,
  // the name of the cohort
  "name": "Mercy General Hospital",
  // free-text description of the cohort
  "description": "Acute care hospitals in the Mercy network.",
  // level in the hierarchy; a root cohort is 1
  "depth": 2,
  // the status of the cohort
  "workflow_state": "active",
  // the unique SIS identifier within the root account
  "sis_source_id": "HS-MERCY-GEN",
  // the SIS import that last touched the cohort, if any
  "sis_batch_id": 12,
  // fields last changed outside SIS; a later SIS import leaves these alone
  "stuck_sis_fields": ["name"],
  // when the cohort was created
  "created_at": "2026-01-15T10:00:00Z",
  // when the cohort was last updated
  "updated_at": "2026-01-15T10:00:00Z",
  // the number of active members; present with include[]=member_count
  "member_count": 25,
  // the number of active leaders; present with include[]=leader_count
  "leader_count": 2,
  // the number of active cohorts one level below; present with
  // include[]=child_count
  "child_count": 3,
  // the chain of cohorts from the root down to the parent, root first; present
  // with include[]=ancestors
  "ancestors": null
}

A CohortTreeNode object looks like:

// A cohort and the subtree beneath it.
{
  // the cohort at this node
  "cohort": null,
  // active direct children, newest first, capped at 100 per node
  "children": null,
  // true when this node has children that the requested depth cut off; fetch the
  // subtree again from this node to see them
  "truncated": false,
  // true when this node has more than 100 active direct children and children
  // holds only the first 100; list with parent_cohort_id set to this node's id
  // for the complete set; independent of truncated
  "children_truncated": false
}

List cohorts CohortsController#index

GET /api/v1/accounts/:account_id/cohorts

Scope: url:GET|/api/v1/accounts/:account_id/cohorts

List the cohorts placed directly in the account, or the direct children of one cohort. Results are paginated. Without parent_cohort_id, the caller needs account-level permission; cohort leaders get 401.

Request Parameters:

Parameter	Type	Description
roots	boolean	Only list cohorts with no parent. Can't be combined with parent_cohort_id.
parent_cohort_id	integer	List the direct children of a cohort placed in this account.
search_term	string	Only list cohorts whose name contains this text. Needs at least two characters.
sort	string	The field to sort by. Defaults to created_at. Allowed values: `created_at`, `name`, `workflow_state`, `depth`
order	string	The sort direction. Defaults to desc. Ties break by id ascending. Allowed values: `asc`, `desc`
workflow_state[]	string	Only list cohorts in these states. Defaults to active. "all" lists both states. Allowed values: `active`, `deleted`, `all`
include[]	string	Extra data to compute for each cohort. Allowed values: `member_count`, `leader_count`, `child_count`
per_page	integer	The number of cohorts per page. See the pagination section of the API documentation.

Returns a list of Cohort objects

Get a cohort CohortsController#show

GET /api/v1/accounts/:account_id/cohorts/:cohort_id

Scope: url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id

Fetch one cohort by id. A soft-deleted cohort is still returned, with workflow_state "deleted". The cohort can be in any account under the root account; the account in the path is ignored.

Request Parameters:

Parameter		Type	Description
include[]		string	Extra data to compute for the cohort. "ancestors" adds the chain of cohorts from the root down to the parent, root first. Allowed values: `member_count`, `leader_count`, `child_count`, `ancestors`

Returns a Cohort object

Get cohort permissions CohortsController#permissions

GET /api/v1/accounts/:account_id/cohorts/:cohort_id/permissions

Scope: url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id/permissions

Returns permission information for the calling user on the given cohort. A soft-deleted cohort is still answered for callers who can view it. See also the Account counterpart.

Request Parameters:

Parameter		Type	Description
permissions[]		string	List of permissions to check against the authenticated user. Defaults to every cohort permission. Permission names are documented in the List assignable permissions endpoint.

Example Request:

curl https://<canvas>/api/v1/accounts/1/cohorts/4002/permissions \
  -H 'Authorization: Bearer <token>' \
  -d 'permissions[]=manage_cohorts_edit' \
  -d 'permissions[]=manage_cohorts_enroll_in_course'

Example Response:

{"manage_cohorts_edit": true, "manage_cohorts_enroll_in_course": false}

Get a cohort tree CohortsController#tree

GET /api/v1/accounts/:account_id/cohorts/:cohort_id/tree

Scope: url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id/tree

Fetch a cohort with its active descendants as a nested tree. Each node lists at most 100 children, newest first. The cohort can be in any account under the root account; the account in the path is ignored.

Request Parameters:

Parameter		Type	Description
depth		integer	How many levels to return, from 1 to 10. Defaults to 2.

Returns a CohortTreeNode object

List member candidates CohortsController#member_candidates

GET /api/v1/accounts/:account_id/cohorts/:cohort_id/member_candidates

Scope: url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id/member_candidates

List the users who can be added as members of a cohort, ordered by sortable name and paginated. Users who are already active members are left out. An account admin with read_roster on the cohort's account sees the users of that account and its sub-accounts. A cohort leader whose role can add members sees the active members of the shallowest cohort they lead that contains this cohort, and of that cohort's sub-cohorts. The cohort can be in any account under the root account; the account in the path is ignored. Every caller can search by name. Searching by login, email, or SIS ID also needs the view_user_logins, read_email_addresses, or read_sis permission respectively.

Request Parameters:

Parameter		Type	Description
search_term		string	Only list users matching this text. Needs at least two characters.
per_page		integer	The number of users per page. See the pagination section of the API documentation.

Returns a list of User objects