🚀 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 Leaders API

List, add and remove the leaders of a cohort. A leader's rights reach the cohort and every cohort beneath it.

A CohortLeader object looks like:

// One leader assignment on one cohort.
{
  // the ID of the assignment, used to update or remove it
  "id": 5501,
  // the cohort the assignment was returned for
  "cohort_id": 4002,
  // the leader
  "user_id": 901,
  // the root account of the cohort
  "root_account_id": 1,
  // the cohort leader role the assignment carries
  "role_id": 12,
  // the role's id, label and base_role_type (always CohortLeader)
  "role": {"id":12,"label":"Cohort Leader","base_role_type":"CohortLeader"},
  // always true; a leader's rights cannot be confined to one level
  "applies_to_descendants": true,
  // true when the assignment lives on an ancestor cohort and was returned because
  // of include_inherited
  "inherited": false,
  // the cohort the assignment actually lives on; equal to cohort_id unless
  // inherited
  "source_cohort_id": 4002,
  // the status of the assignment
  "workflow_state": "active",
  // when the assignment was created
  "created_at": "2026-09-05T13:30:00Z",
  // when the assignment was last updated
  "updated_at": "2026-09-05T13:30:00Z",
  // the leader's display fields: id, name, sortable_name and short_name, plus
  // sis_user_id, login_id and email when the caller holds read_sis (or manage_sis
  // on the root account), view_user_logins or read_email_addresses on the
  // cohort's account; each is null when the leader has no value
  "user": {"id":901,"name":"Dana Okafor","sortable_name":"Okafor, Dana","short_name":"Dana"}
}

List cohort leaders CohortLeadersController#index

GET /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders

Scope: url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders
Return the leaders assigned directly to a cohort, newest first. Paginated.

Request Parameters:

Parameter Type Description
include_inherited boolean Also return the leaders of every ancestor cohort. Those entries carry inherited true and a source_cohort_id naming the ancestor they live on. Defaults to false.
sort string The field to sort by. Defaults to created_at. user_name and user_sortable_name sort on the leader's user. Ties are broken by id, ascending.

Allowed values: created_at, role_id, user_name, user_sortable_name

order string The sort direction. Defaults to desc.

Allowed values: asc, desc

Returns a list of CohortLeader objects

Add a leader to a cohort CohortLeadersController#create

POST /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders

Scope: url:POST|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders
Assign a user as a leader of a cohort. The assignment reaches the cohort and every cohort beneath it. When the user already holds the role on this cohort, the existing assignment is returned unchanged. A removed assignment for the same user and role is reactivated.

Request Parameters:

Parameter Type Description
user_id Required string The user to assign, as an id or an SIS id such as sis_user_id:abc. The user needs an active login in the cohort's root account. A user that doesn't exist or has no such login returns 404.
role_id integer A role whose base type is CohortLeader. Defaults to the built-in Cohort Leader role.
Returns a CohortLeader object

Update a leader's role CohortLeadersController#update

PUT /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id

Scope: url:PUT|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id
Change the role a leader assignment carries. The assignment keeps its created_at; only updated_at advances. When the user already holds the target role on this cohort through a separate assignment, the assignment named in the path is removed and the other one is returned unchanged, which also requires permission to remove leaders. An assignment inherited from an ancestor cohort must be updated on the cohort that owns it.

Request Parameters:

Parameter Type Description
role_id Required integer A role whose base type is CohortLeader.
Returns a CohortLeader object

Remove a leader from a cohort CohortLeadersController#destroy

DELETE /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id

Scope: url:DELETE|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id
Soft-delete a leader assignment that lives on this cohort. An assignment inherited from an ancestor cohort must be removed from the cohort that owns it. Returns a CohortLeader object