🚀 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.
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 10 levels deep.
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
}
Get a cohort CohortsController#show
GET /api/v1/accounts/:account_id/cohorts/:cohort_id
Scope:
Fetch one cohort by id. A soft-deleted cohort is still returned, with
workflow_state "deleted".
url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id
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: |