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

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