Developers
Gamification

Retrieve the points ranking

GET/gamification/rankings

Returns the users ranked by points earned in the selected period. When period is omitted, all-time points are used; when limit is omitted, up to 100 positions are returned.

Results are limited to the products and users accessible with the current credentials. Filtering by product_id narrows that scope and never widens it: requesting products outside the scope returns an empty ranking.

Each entry includes the user's name and avatar only when the credentials also have the users.read permission; otherwise the user object is null.

Rankings are eventually consistent. Manual point adjustments are reflected on the next request, while automatically awarded points may take up to cache_ttl_seconds to appear.

Authorization

AuthorizationBearer <token>

Autonomous mode: the API credential secret, sent as a bearer token. Credential secrets are identified by a fixed prefix.

In: header

Query Parameters

period?string

Value in

  • "all"
  • "today"
  • "last_7_days"
  • "last_30_days"
  • "custom"
from?string

Required when period is custom.

Formatdate
to?string

Required when period is custom.

Formatdate
product_id?array<string>
limit?integer
Range1 <= value <= 100

Header Parameters

X-Client-Request-Id?string

Optional client-generated identifier of the request, up to 64 characters from [A-Za-z0-9._-]. Echoed back in the response and recorded in the request log; it never replaces the server-generated X-Request-Id.

Lengthlength <= 64

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/gamification/rankings"
{  "data": {    "cache_ttl_seconds": 0,    "entries": [      {        "points": 0,        "position": 0,        "user": {          "avatar": "string",          "name": "string"        },        "user_id": "string"      }    ],    "generated_at": "2019-08-24T14:15:22Z",    "object": "ranking",    "period": {      "from": "2019-08-24T14:15:22Z",      "kind": "all",      "to": "2019-08-24T14:15:22Z"    },    "scope": {      "product_ids": [        "string"      ]    },    "summary": {      "participants": 0,      "total_points": 0    }  }}

Gamification

Gamification in API v3: retrieve the points ranking, list point entries.

List point entries GET

Returns point entries from the points ledger, using cursor-based pagination. Points awarded automatically (lessons, comments, questions, exams, course milestones, and certificates) and manual adjustments are returned in the same collection and can be distinguished with the `origin` filter. Resetting a user's progress or revoking a certificate does not remove previously awarded points. Reopening or deleting an exam attempt removes the points awarded for passing it, and the corresponding entries no longer appear in the collection. Results are limited to the users and products accessible with the current credentials.