Rank learners by engagement

GET/v1/organization/{orgId}/learning/workspace/engagement/learners

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Everyone learning (a course, quiz, credit claim or certification, or a session or event attended), ranked by Learning's view of the one engagement score, where learning counts more and events and campaigns still count. Each with the score, its band, why (for example "72 = 3 courses · 4.5 credits · certified · 2 webinars"), the overall score and what they did. counts gives the number in each band before band filters. A teammate limited to some credits portfolios ranks only those portfolios' people. Reads only. Requires read:learning; refused for a key restricted to particular events. Also at GET /v1/learning/workspace/engagement/learners.

Request example

curl --request GET \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/learning/workspace/engagement/learners' \
  --header 'x-access-token: <api-token>'

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/learning/workspace/engagement/learners', {
  method: 'GET',
  headers: {
    "x-access-token": "<api-token>"
  },
});

const data = await response.json();
console.log(data);

import requests

response = requests.request(
    "GET",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/learning/workspace/engagement/learners",
    headers={
        "x-access-token": "<api-token>"
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/learning/workspace/engagement/learners",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://public-api.sessionboard.com/v1/organization/{orgId}/learning/workspace/engagement/learners", nil)
  req.Header.Add("x-access-token", "<api-token>")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/learning/workspace/engagement/learners"))
    .header("x-access-token", "<api-token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

Response headers

Authorizations

x-access-tokenstringheader
Organization API token. Generate from Organization Settings → API Tokens.
AuthorizationBearer <token>headeror
OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

orgIdstringpathrequired
Your organization ID. Any other organization returns 404.

Query parameters

bandstringquery
warming (Warming up), engaged (Engaged), highly (Highly engaged).
Allowed values
"warming", "engaged", "highly"
eventIdintegerquery
Only people tied to this event.
Minimum
1
limitintegerquery
Default
25
Minimum
1
Maximum
200
offsetintegerquery
Default
0
Minimum
0

Responses

200`application/json`

successboolean
payloadobject
Show child attributes
- linesLearningEngagementLines
  The scores where the bands start (default 50 and 80).
  Show child attributes
  - engagednumber
  - highlynumber
- totalinteger
  Learners in the list after band, before paging.
- countsLearningEngagementBandCounts
  Show child attributes
  - warminginteger
  - engagedinteger
  - highlyinteger
- learnersLearningRankedLearner[]
  Show child attributes
  - person_idstring<uuid> | null
  - keystring | null
    The person's key in People.
  - namestring
  - emailstring
  - scoreinteger
    Minimum
    0
    Maximum
    100
  - bandstring
    warming (Warming up), engaged (Engaged), highly (Highly engaged).
    Allowed values
    "warming", "engaged", "highly"
  - band_labelstring
  - whystring
    The score as a sentence, e.g. 72 = 3 courses · 4.5 credits · certified · 2 webinars.
  - overallobject
    Show child attributes
    scoreinteger
    Minimum
    0
    Maximum
    100
    bandstring
    warming (Warming up), engaged (Engaged), highly (Highly engaged).
    Allowed values
    "warming", "engaged", "highly"
    whystring
  - courses_completedinteger
  - courses_startedinteger
  - creditsnumber
  - certificationsinteger

400`application/json`

A path, query or body value failed validation, or an unknown body property was sent. message names the field. (A source object naming the assistant, with the person's prompt, is accepted on every write and removed before validation.) For an {eventId} path that is not a whole number: error: VALIDATION_ERROR, eventId must be a valid integer.

Gateway errors carry error (a code) and message. Errors from Learning itself carry status, success: false, message, name, and sometimes code (and feature or paused_at).

errorstring | object
The gateway's error code (SCOPE_REQUIRED, ORG_WIDE_TOKEN_REQUIRED, NOT_FOUND, …).
messagestring
statusinteger
successboolean
namestring
codestring
FEATURE_NOT_ENABLED, AGENT_WRITES_PAUSED, …
featurestring
paused_atstring<date-time>

401

Missing, invalid or expired token.

403`application/json`

SCOPE_REQUIRED — the token lacks read:learning (reads) or write:learning (writes). Legacy tokens with no scopes cannot write.
ORG_WIDE_TOKEN_REQUIRED — the token is restricted to particular events: "The Learning workspace covers every event and learner in the organization, so this API key (restricted to particular events) cannot use it. Use a key without an event restriction."
FEATURE_NOT_ENABLED (feature: lessons_credits) — Learning is not on for the organization.
FORBIDDEN — the token's user is not an active member of the organization, or lacks the Lessons permission the operation needs.

Gateway errors carry error (a code) and message. Errors from Learning itself carry status, success: false, message, name, and sometimes code (and feature or paused_at).

errorstring | object
The gateway's error code (SCOPE_REQUIRED, ORG_WIDE_TOKEN_REQUIRED, NOT_FOUND, …).
messagestring
statusinteger
successboolean
namestring
codestring
FEATURE_NOT_ENABLED, AGENT_WRITES_PAUSED, …
featurestring
paused_atstring<date-time>

404`application/json`

orgId is not your organization (error: NOT_FOUND, message: Organization not found).

Gateway errors carry error (a code) and message. Errors from Learning itself carry status, success: false, message, name, and sometimes code (and feature or paused_at).

errorstring | object
The gateway's error code (SCOPE_REQUIRED, ORG_WIDE_TOKEN_REQUIRED, NOT_FOUND, …).
messagestring
statusinteger
successboolean
namestring
codestring
FEATURE_NOT_ENABLED, AGENT_WRITES_PAUSED, …
featurestring
paused_atstring<date-time>

429`application/json`

The token's request limit (100 requests per 15 minutes per bucket by default — see Rate Limiting). Wait Retry-After seconds.
QUOTA_EXCEEDED (writes) — the token's daily write quota (10,000 a day). Resets at midnight UTC.

Gateway errors carry error (a code) and message. Errors from Learning itself carry status, success: false, message, name, and sometimes code (and feature or paused_at).

errorstring | object
The gateway's error code (SCOPE_REQUIRED, ORG_WIDE_TOKEN_REQUIRED, NOT_FOUND, …).
messagestring
statusinteger
successboolean
namestring
codestring
FEATURE_NOT_ENABLED, AGENT_WRITES_PAUSED, …
featurestring
paused_atstring<date-time>

Retry-Afterintegerheader
Seconds to wait before retrying.

Response examples

{
  "success": true,
  "payload": {
    "lines": {
      "engaged": 123.45,
      "highly": 123.45
    },
    "total": 123,
    "counts": {
      "warming": 123,
      "engaged": 123,
      "highly": 123
    },
    "learners": [
      {
        "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "key": "<string>",
        "name": "<string>",
        "email": "<string>",
        "score": 0,
        "band": "warming",
        "band_label": "<string>",
        "why": "<string>",
        "overall": {
          "score": 0,
          "band": "warming",
          "why": "<string>"
        },
        "courses_completed": 123,
        "courses_started": 123,
        "credits": 123.45,
        "certifications": 123
      }
    ]
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123,
  "success": true,
  "name": "<string>",
  "code": "<string>",
  "feature": "<string>",
  "paused_at": "2026-01-15T09:30:00Z"
}

{
  "error": "ORG_WIDE_TOKEN_REQUIRED",
  "message": "The Learning workspace covers every event and learner in the organization, so this API key (restricted to particular events) cannot use it. Use a key without an event restriction."
}

{
  "error": "SCOPE_REQUIRED",
  "message": "This operation requires the 'write:learning' scope."
}

{
  "status": 403,
  "success": false,
  "message": "Feature 'lessons_credits' is not enabled for this organization",
  "name": "FeatureNotEnabledError",
  "code": "FEATURE_NOT_ENABLED",
  "feature": "lessons_credits"
}

{
  "error": "NOT_FOUND",
  "message": "Organization not found"
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123,
  "success": true,
  "name": "<string>",
  "code": "<string>",
  "feature": "<string>",
  "paused_at": "2026-01-15T09:30:00Z"
}

Rank learners by engagement

Request example

Try it

Authorizations

Path parameters

Query parameters

Responses

200application/json

400application/json

401

403application/json

404application/json

429application/json

Response examples

200`application/json`

400`application/json`

403`application/json`

404`application/json`

429`application/json`