> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/canvas/resources/cohorts.md).

# Cohorts

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 href="#cohort" id="cohort"></a>

```js
// 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. Each ancestor carries the counts also requested in
  // include[]
  "ancestors": null
}
```

#### A CohortTreeNode object looks like: <a href="#cohorttreenode" id="cohorttreenode"></a>

```js
// 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](#method.cohorts.index) <a href="#method.cohorts.index" id="method.cohorts.index"></a>

[CohortsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `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`  | <p>Only list cohorts whose name contains this text. Needs at least two<br>characters.</p>                                                                             |
| `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`  | <p>Only list cohorts in these states. Defaults to active. "all" lists both<br>states. Allowed values: <code>active</code>, <code>deleted</code>, <code>all</code></p> |
| `include[]`        | `string`  | Extra data to compute for each cohort. Allowed values: `member_count`, `leader_count`, `child_count`                                                                  |
| `per_page`         | `integer` | <p>The number of cohorts per page. See the pagination section of the API<br>documentation.</p>                                                                        |

Returns a list of [Cohort](#cohort) objects.

## [List the cohorts I lead](#method.cohorts.led) <a href="#method.cohorts.led" id="method.cohorts.led"></a>

[CohortsController#led](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `GET /api/v1/cohorts`

**Scope:** `url:GET|/api/v1/cohorts`

List the top-level cohorts the caller leads across the root account. A led cohort is hidden when the caller also leads one of its active ancestors. With search\_term, search instead covers every cohort the caller leads or that sits below an active cohort they lead, returned flat. This endpoint checks no permission of its own. Results are paginated.

#### Request Parameters:

| Parameter          | Type      | Description                                                                                                                                                                                                                |
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_term`      | `string`  | <p>Search all cohorts the caller leads or that sit below an active cohort<br>they lead, at any depth, and list those whose name contains this text,<br>flat rather than top-level only. Needs at least two characters.</p> |
| `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`  | <p>Only list cohorts in these states. Defaults to active. "all" lists both<br>states. Allowed values: <code>active</code>, <code>deleted</code>, <code>all</code></p>                                                      |
| `include[]`        | `string`  | Extra data to compute for each cohort. Allowed values: `member_count`, `leader_count`, `child_count`                                                                                                                       |
| `per_page`         | `integer` | <p>The number of cohorts per page. See the pagination section of the API<br>documentation.</p>                                                                                                                             |

Returns a list of [Cohort](#cohort) objects.

## [Get a cohort](#method.cohorts.show) <a href="#method.cohorts.show" id="method.cohorts.show"></a>

[CohortsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `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` | <p>Extra data to compute for the cohort. "ancestors" adds the chain of<br>cohorts from the root down to the parent, root first. Counts requested<br>alongside "ancestors" are computed for each ancestor too, so one request<br>tells which ancestors have more children to load. Allowed values: <code>member\_count</code>, <code>leader\_count</code>, <code>child\_count</code>, <code>ancestors</code></p> |

Returns a [Cohort](#cohort) object.

## [Get cohort permissions](#method.cohorts.permissions) <a href="#method.cohorts.permissions" id="method.cohorts.permissions"></a>

[CohortsController#permissions](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `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](https://developerdocs.instructure.com/pages/hce5iQ0q3r606RoR4Dor#method.accounts.permissions) counterpart.

#### Request Parameters:

| Parameter       | Type     | Description                                                                                                                                                                                                                                                                                                             |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `permissions[]` | `string` | <p>List of permissions to check against the authenticated user. Defaults<br>to every cohort permission. Permission names are documented in the<br><a href="https://developerdocs.instructure.com/pages/f7Drit9p3HR5ij8XDF4s#method.role_overrides.manageable_permissions">List assignable permissions</a> endpoint.</p> |

#### Example Request:

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

#### Example Response:

```js
{"manage_cohorts_edit": true, "manage_cohorts_add_members": false}
```

## [Get a cohort tree](#method.cohorts.tree) <a href="#method.cohorts.tree" id="method.cohorts.tree"></a>

[CohortsController#tree](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `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](#cohorttreenode) object.

## [List member candidates](#method.cohorts.member_candidates) <a href="#method.cohorts.member_candidates" id="method.cohorts.member_candidates"></a>

[CohortsController#member\_candidates](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `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 or leaders of a cohort, ordered by sortable name and paginated. With purpose "members" (the default) the caller needs manage\_cohorts\_add\_members on the cohort and users who are already active members are left out. With purpose "leaders" the caller needs manage\_cohorts\_add\_leaders and current members are included, since a member can be made a leader.

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 carries the purpose's permission 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.                                |
| `purpose`     | `string`  | What the picked users will be added as. Defaults to members. Allowed values: `members`, `leaders` |
| `per_page`    | `integer` | <p>The number of users per page. See the pagination section of the API<br>documentation.</p>      |

Returns a list of [User](https://developerdocs.instructure.com/services/canvas/resources/users.md#user) objects.

## [List assignable leader roles](#method.cohorts.assignable_roles) <a href="#method.cohorts.assignable_roles" id="method.cohorts.assignable_roles"></a>

[CohortsController#assignable\_roles](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `GET /api/v1/accounts/:account_id/cohorts/:cohort_id/assignable_roles`

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

List the cohort roles the caller may assign when adding a leader to a cohort, paginated. The caller needs manage\_cohorts\_add\_leaders on the cohort. A role is assignable when every cohort permission it carries is one the caller holds on the cohort, so nobody can hand out a role broader than their own. The built-in Cohort Leader role comes first, then custom cohort roles by name. A deleted cohort returns 404.

#### Request Parameters:

| Parameter  | Type      | Description                                                                                  |
| ---------- | --------- | -------------------------------------------------------------------------------------------- |
| `per_page` | `integer` | <p>The number of roles per page. See the pagination section of the API<br>documentation.</p> |

#### Example Response:

```js
[{ "id": 12, "label": "Cohort Leader", "base_role_type": "CohortLeader" }]
```

## [Create a cohort](#method.cohorts.create) <a href="#method.cohorts.create" id="method.cohorts.create"></a>

[CohortsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `POST /api/v1/accounts/:account_id/cohorts`

**Scope:** `url:POST|/api/v1/accounts/:account_id/cohorts`

Create a cohort in the account. Set cohort\[parent\_cohort\_id] to null to create a root cohort, or to the id of an active cohort in the same account to create a sub-cohort under it. Sub-cohorts need permission to create cohorts on the parent; root cohorts need it on the account.

Responds with 400 and error\_code max\_depth\_exceeded when the parent is already at the depth limit, or max\_cohorts\_exceeded when the root account is at its active cohort limit.

#### Request Parameters:

| Parameter                  | Type               | Description                                                                                                                            |
| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `cohort[name]`             | Required `string`  | The name of the cohort, up to 255 characters.                                                                                          |
| `cohort[parent_cohort_id]` | Required `integer` | <p>The id of the parent cohort, or null to create a root cohort. The key<br>must be present.</p>                                       |
| `cohort[description]`      | `string`           | Free-text description, up to 500 characters.                                                                                           |
| `cohort[sis_source_id]`    | `string`           | <p>The SIS identifier, up to 255 characters and unique within the root<br>account. Setting it requires the manage\_sis permission.</p> |

Returns a [Cohort](#cohort) object.

## [Update a cohort](#method.cohorts.update) <a href="#method.cohorts.update" id="method.cohorts.update"></a>

[CohortsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `PUT /api/v1/accounts/:account_id/cohorts/:cohort_id`

**Scope:** `url:PUT|/api/v1/accounts/:account_id/cohorts/:cohort_id`

Change the name, description, or SIS identifier of a cohort. Send at least one of the three. The parent, account, and depth of a cohort never change. A deleted cohort cannot be updated.

#### Request Parameters:

| Parameter                 | Type      | Description                                                                                                                                                                                                                    |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cohort[name]`            | `string`  | The name of the cohort, up to 255 characters.                                                                                                                                                                                  |
| `cohort[description]`     | `string`  | Free-text description, up to 500 characters.                                                                                                                                                                                   |
| `cohort[sis_source_id]`   | `string`  | <p>The SIS identifier, up to 255 characters and unique within the root<br>account. Changing it requires the manage\_sis permission.</p>                                                                                        |
| `override_sis_stickiness` | `boolean` | <p>Default is true. If false, name and description values that were last<br>changed outside SIS ("sticky" fields, listed in stuck\_sis\_fields) are<br>left as they are, and the other submitted fields are still applied.</p> |

Returns a [Cohort](#cohort) object.

## [Delete a cohort](#method.cohorts.destroy) <a href="#method.cohorts.destroy" id="method.cohorts.destroy"></a>

[CohortsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohorts_controller.rb)

#### `DELETE /api/v1/accounts/:account_id/cohorts/:cohort_id`

**Scope:** `url:DELETE|/api/v1/accounts/:account_id/cohorts/:cohort_id`

Soft-delete a cohort and its memberships and leaders. Enrollments are not changed. Deleting an already deleted cohort succeeds without changes.

Responds with 400 and error\_code cohort\_has\_children when the cohort has active child cohorts.

Returns a [Cohort](#cohort) object.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developerdocs.instructure.com/services/canvas/resources/cohorts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
