Skip to content
RetorioRetorio API Docs

List cohorts

GET
/cohorts
curl --request GET \
  --url https://api.retorio.com/be/v2/cohorts \
  --header 'Authorization: Bearer <token>'

Lists your organization’s cohorts with aggregate participant and token counts. It is the usual first call before inviting or removing anyone, to find the cohort id and type you need.

Authentication

Section titled “Authentication”
Auth
Access key
Roles
Owner / Admin / Custom

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
includeBenchmarkingCohorts

true returns only benchmarking cohorts and any other non-empty value only the others. Absent or empty returns both.

string

true returns only benchmarking cohorts and any other non-empty value only the others. Absent or empty returns both.

includeRecordingSessions

true adds programs to each cohort and computes recordingSessions. Any other value or none omits programs and leaves recordingSessions at 0.

string

true adds programs to each cohort and computes recordingSessions. Any other value or none omits programs and leaves recordingSessions at 0.

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
Array
object
extId
required
string
<= 64 characters
name
required
string
<= 255 characters
createdAt
required
string format: date-time
isForBenchmarking
required
boolean
type
required
string
Allowed values: email token
participants
required

Total participants in the cohort.

integer
activeTokens
required

Generated tokens already redeemed by a coaching user.

integer
availableTokens
required

Generated tokens not yet redeemed.

integer
programs

How many programs the cohort has assigned, whatever each assignment’s period (an upcoming or finished assignment counts, an unassigned one does not). Always present on GET /cohorts/{id}. On GET /cohorts it is present only with includeRecordingSessions=true.

integer
recordingSessions
required

Attempts with a result, not deleted, made through the cohort’s current program assignments. Only GET /cohorts?includeRecordingSessions=true computes it. It is 0 everywhere else, including GET /cohorts/{id}.

integer
activeEmails
required

Email-invited users who have completed registration.

integer

Example 

[
  {
    "type": "email"
  }
]

400

Section titled “400”

A query parameter is not valid, for example one sent more than once.

Media typeapplication/json
object
message
required
string
status
required

Canonical error name, e.g. INVALID_ARGUMENT.

string
details
nullable

Example generated

{
  "message": "example",
  "status": "example",
  "details": "example"
}

401

Section titled “401”

Not authenticated: the bearer token is missing, malformed, expired or revoked, its sign-in method does not match your organization’s configuration, the user it belongs to was removed, or your organization is deactivated.

Media typeapplication/json
object
message
required
string
status
required

Canonical error name, e.g. INVALID_ARGUMENT.

string
details
nullable

Example generated

{
  "message": "example",
  "status": "example",
  "details": "example"
}

403

Section titled “403”

Refused: the token does not belong to an admin, or your organization does not have the coaching product, or the admin’s roles do not grant cohorts:view.

Media typeapplication/json
Any of:
object
message
required
string
status
required

Canonical error name, e.g. INVALID_ARGUMENT.

string
details
nullable

Example generated

{
  "message": "example",
  "status": "example",
  "details": "example"
}

500

Section titled “500”

Internal Server Error

Media typeapplication/json
object
key
additional properties
nullable

Example generated

{
  "additionalProperty": "example"
}

Retorio is GDPR and DSGVO compliant, EU AI Act aligned, ISO 27001 certified, and hosted on Google Cloud with EU data residency. For anything specific to your rollout, ask your Retorio contact.