> 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/cohort_members.md).

# Cohort Members

List, add and remove the people in a cohort.

#### A CohortMembership object looks like: <a href="#cohortmembership" id="cohortmembership"></a>

```js
// One person's place in one cohort.
{
  // the ID of the membership
  "id": 9001,
  // the cohort the membership belongs to
  "cohort_id": 4002,
  // the member
  "user_id": 17,
  // the root account of the cohort
  "root_account_id": 1,
  // the status of the membership
  "workflow_state": "active",
  // the SIS import that last touched the membership, if any
  "sis_batch_id": 12,
  // when the user was added
  "created_at": "2026-01-15T10:00:00Z",
  // when the membership was last updated
  "updated_at": "2026-01-15T10:00:00Z",
  // the member's latest request in this root account; null without the view
  // analytics permission
  "last_activity_at": "2026-01-20T08:30:00Z",
  // whether the member leads this cohort or one of its ancestors
  "is_leader": false,
  // the member's active institutional tags visible from the cohort's account, as
  // id and name; empty unless institutional tags are enabled and the caller can
  // view them
  "institutional_tags": [{"id":5,"name":"Honors"}],
  // the member's role in this cohort as id and label: the cohort role they lead
  // this cohort or one of its ancestors with, or Member with a null id. A member
  // leading through several assignments gets the one on the nearest cohort, and
  // the earliest assignment there
  "role": {"id":12,"label":"Cohort Leader"},
  // the member's display fields: id, name, sortable_name, short_name, email (null
  // without read_email_addresses), sis_user_id (null without read_sis or
  // manage_sis), login_id (null without view_user_logins), time_zone (a Rails
  // time zone name), last_login (null without the view analytics permission),
  // account_status (active, suspended or deleted, from logins in this root
  // account), and avatar_url when avatars are enabled
  "user": {"id":17,"name":"Dana Okafor","sortable_name":"Okafor, Dana","short_name":"Dana","email":"dana@example.com","sis_user_id":"S17","login_id":"dana","time_zone":"Mountain Time (US \u0026 Canada)","last_login":null,"account_status":"active"}
}
```

## [List cohort members](#method.cohort_members.index) <a href="#method.cohort_members.index" id="method.cohort_members.index"></a>

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

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

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

Return the memberships of a cohort, newest first. Paginated.

#### Request Parameters:

| Parameter             | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workflow_state[]`    | `string`  | <p>Which memberships to return. Repeat to pass several states. all returns<br>both active and deleted. Defaults to active. Allowed values: <code>active</code>, <code>deleted</code>, <code>all</code></p>                                                                                                                                                                                                                                 |
| `sort`                | `string`  | <p>The field to sort by. Defaults to created\_at. user\_name and<br>user\_sortable\_name sort on the member's user. last\_activity\_at sorts on<br>the member's latest login activity in the root account, with no activity<br>last in either order, and requires the view analytics permission. Allowed values: <code>created\_at</code>, <code>user\_name</code>, <code>user\_sortable\_name</code>, <code>last\_activity\_at</code></p> |
| `order`               | `string`  | The sort direction. Defaults to desc. Allowed values: `asc`, `desc`                                                                                                                                                                                                                                                                                                                                                                        |
| `search_term`         | `string`  | <p>A partial, case-insensitive match against the member's name, sortable<br>name or short name, and in the cohort's root account against SIS ID when<br>the caller can read SIS data, email when the caller can read email<br>addresses, and login ID when the caller can view logins. Must be at<br>least 2 characters.</p>                                                                                                               |
| `include_descendants` | `boolean` | <p>Also return the memberships of active cohorts beneath this one. Each row<br>is one membership, so a user in several cohorts appears once per cohort.<br>Defaults to false.</p>                                                                                                                                                                                                                                                          |

Returns a list of [CohortMembership](#cohortmembership) objects.

## [Add members to a cohort](#method.cohort_members.create) <a href="#method.cohort_members.create" id="method.cohort_members.create"></a>

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

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

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

Add existing users to a cohort. Ids that cannot be added are reported under skipped.

Skip reasons are already\_member, user\_not\_found, user\_not\_in\_root\_account and not\_in\_leader\_scope. A cohort leader without an account grant can only add users who already belong to the cohort subtree they lead, and every id outside that subtree is reported as not\_in\_leader\_scope.

#### Request Parameters:

| Parameter    | Type               | Description                                                                                                                          |
| ------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `user_ids[]` | Required `integer` | <p>The users to add, 1 to 100 ids. Each user needs an active login in the<br>cohort's root account. Repeated ids are added once.</p> |

#### Example Response:

```js
{ "added": [CohortMembership], "skipped": [{ "user_id": 18, "reason": "already_member" }] }
```

## [Remove a member from a cohort](#method.cohort_members.destroy) <a href="#method.cohort_members.destroy" id="method.cohort_members.destroy"></a>

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

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

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

Soft-delete a user's active membership in this cohort. Memberships in child cohorts are not changed. Adding the user again reactivates the same membership.

#### Request Parameters:

| Parameter | Type               | Description                                    |
| --------- | ------------------ | ---------------------------------------------- |
| `user_id` | Required `integer` | The member to remove, as a local or global id. |

Returns a [CohortMembership](#cohortmembership) object.

## [Remove members from a cohort](#method.cohort_members.bulk_destroy) <a href="#method.cohort_members.bulk_destroy" id="method.cohort_members.bulk_destroy"></a>

[CohortMembersController#bulk\_destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/cohort_members_controller.rb)

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

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

Soft-delete the active memberships of several users in this cohort. Memberships in child cohorts and course enrolments are not changed. Adding a user again reactivates the same membership. Ids that cannot be removed are reported under skipped.

Skipped entries repeat the id as it was sent; a numeric id comes back as an integer. Skip reasons are not\_a\_member and user\_not\_found.

#### Request Parameters:

| Parameter    | Type              | Description                                                                                                                                                                                            |
| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_ids[]` | Required `string` | <p>The users to remove, 1 to 100 ids. Each is a local or global id, "self",<br>or an SIS id such as sis\_user\_id:abc, as in other Canvas APIs. Repeated<br>references to one user remove it once.</p> |

#### Example Response:

```js
{ "removed": [CohortMembership], "skipped": [{ "user_id": 18, "reason": "not_a_member" }] }
```


---

# 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/cohort_members.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.
