🚀 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.
Cohort Members API
List, add and remove the people in a cohort.
A CohortMembership object looks like:
// 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"}],
// reserved; always null for now
"role": null,
// 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 CohortMembersController#index
GET /api/v1/accounts/:account_id/cohorts/:cohort_id/members
Scope:
Return the memberships of a cohort, newest first. Paginated.
url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id/members
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| workflow_state[] | string |
Which memberships to return. Repeat to pass several states. all returns
both active and deleted. Defaults to active.
Allowed values: |
|
| sort | string |
The field to sort by. Defaults to created_at. user_name and
user_sortable_name sort on the member's user. last_activity_at sorts on
the member's latest login activity in the root account, with no activity
last in either order, and requires the view analytics permission.
Allowed values: |
|
| order | string |
The sort direction. Defaults to desc.
Allowed values: |
|
| search_term | string | A partial, case-insensitive match against the member's name, sortable name or short name, and in the cohort's root account against SIS ID when the caller can read SIS data, email when the caller can read email addresses, and login ID when the caller can view logins. Must be at least 2 characters. | |
| include_descendants | boolean | Also return the memberships of active cohorts beneath this one. Each row is one membership, so a user in several cohorts appears once per cohort. Defaults to false. |
Add members to a cohort CohortMembersController#create
POST /api/v1/accounts/:account_id/cohorts/:cohort_id/members
Scope:
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.
url:POST|/api/v1/accounts/:account_id/cohorts/:cohort_id/members
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| user_ids[] | Required | integer | The users to add, 1 to 100 ids. Each user needs an active login in the cohort's root account. Repeated ids are added once. |
Example Response:
{ "added": [CohortMembership], "skipped": [{ "user_id": 18, "reason": "already_member" }] }
Remove a member from a cohort CohortMembersController#destroy
DELETE /api/v1/accounts/:account_id/cohorts/:cohort_id/members/:user_id
Scope:
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.
url:DELETE|/api/v1/accounts/:account_id/cohorts/:cohort_id/members/:user_id
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| user_id | Required | integer | The member to remove, as a local or global id. |