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

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: 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 Which memberships to return. Repeat to pass several states. all returns both active and deleted. Defaults to active.

Allowed values: active, deleted, all

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: created_at, user_name, user_sortable_name, last_activity_at

order string The sort direction. Defaults to desc.

Allowed values: asc, desc

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.
Returns a list of CohortMembership objects

Add members to a cohort CohortMembersController#create

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 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: 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 object