List all user (path session) statistics: Migration guide

We've combined the getUsersPathSessionStatsand getUserPathSessionStats endpoints from API v1 into a single, more efficient endpoint in API v2: List all user (path session) statistics.

This guide outlines the key differences you'll encounter when moving to API v2:

From getUsersPathSessionStats
From getUserPathSessionStats

💡
Key changes

Pagination: The v2 endpoint is paginated and returns 200 path session statistics per page.

`getUsersPathSessionStats` migration

Documentation links

Here are the links to the API reference for:

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

API v1: /api/v1/paths/sessions/:sessionId/stats/users
API v2: /api/v2/paths/{pathId}/sessions/{sessionId}/user-stats

Input changes

This section details the specific alterations to the input requirements between API versions.

API v1 input example

curl --location -g 'https://{{host}}/api/v1/paths/sessions/60ad14abc2615a51213dbce9/stats/users?company={{company}}&apiKey={{apiKey}}'

API v2 input example

curl --request GET \
     --url https://app.360learning.com/api/v2/paths/507f1f77bcf86cd799439011/sessions/507f1f77bcf86cd799439011/user-stats \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json'

Main input differences

Change type	API v1	API v2
Modified Query parameters	`ccompletedBefore` / `completedAfter` (Optional): Timestamp filters, in the format`YYYY-MM-DDTHH:mm:ss.sssZ`.	`completedAt` (Optional): Modified name, functionality, syntax, and date format. Now, this single filter combines the functionalities of `completedAtBefore` and `completedAtAfter`. It filters stats by completion date range using the LHS bracket notation. The date format is now `YYYY-MM-DD`.
Added Query parameter		`userId` (Optional): Filter the stats for a specific user using its unique ID.

Output changes

This section details the specific alterations to the successful output returned between API versions.

API v1 output example

{
  "sessionId": "6307bb305ab5e0ebdb1138e8",
  "sessionName": "Onboarding session",
  "pathName": "First Path",
  "pathId": "6307bb2f66977c8e2316d6d5",
  "usersStats": [
    {
      "_id": "62bdbc00293a604543f44386",
      "deleted": false,
      "firstName": "Jean",
      "lastName": "Martin",
      "mail": "[email protected]",
      "totalTimeSpentInSeconds": 96.455,
      "progress": 50,
      "score": 38,
      "completedAt": "2022-08-25T18:11:55.650Z",
      "detailedStatus": {
        "type": "onTime"
      },
      "certificate": false,
      "status": "onTime",
      "customFields": []
    }
  ]
}

API v2 output example

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "progress": 0,
    "status": {
      "type": "awaitingCorrection"
    },
    "timeSpent": 0,
    "userId": "507f1f77bcf86cd799439011",
    "completedAt": "2025-07-01T08:17:42.042Z",
    "score": 0,
    "enrolledAt": "2025-07-01T08:17:42.042Z",
    "unenrolledAt": "2025-07-01T08:17:42.042Z",
    "certificateId": "507f1f77bcf86cd799439011",
    "selfEnrolled": true,
    "startedAt": "2025-07-01T08:17:42.042Z",
    "dueDate": "2025-07-01T08:17:42.042Z"
  }
]

Main output differences

API v2 output has been flattened: no more sub-objects in the response body, you only get raw stats.

API v2 introduces pagination for the List all user (path session) statistics endpoint. Instead of returning all stats in a single response, it now returns a maximum of 2000 statistics per page. To retrieve subsequent pages, you need to follow the URL provided in the Link header of the response.

Change type	API v1	API v2
Removed Output property	`pathName`: Removed and not replaced in v2.
Removed Output property	`sessionName`: Removed and not replaced in v2.
Modified Output property	`totalTimeSpentInSeconds`: Time spent (in millis) by the learner on this path session.	`timeSpent`: (Required) Time spent (in millis) by the learner on this path session.
Modified Output property	`detailedStatus`: Detailed status of the user in the path session.	`status`: (Required) Detailed status of the user in the path session.
Added Output property		`enrolledAt` : (Required) date of enrollment of the learner in this path session,in the format`YYYY-MM-DDTHH:mm:ss.sssZ`
Added Output property		`unenrolledAt` : (Optional) date of unenrollment of the learner in this path session,in the format`YYYY-MM-DDTHH:mm:ss.sssZ`
Added Output property		`selfEnrolled` : (Required) indicate whether the learner self-enrolled to this path session or not.
Added Output property		`certificateId` : (Optional) The ID of the certificate obtained by the user in the session.

`getUserPathSessionStats` migration

Documentation links

Here are the links to the API reference for:

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

API v1: /api/v1/paths/sessions/:sessionId/stats/:userEmailOrId
API v2: /api/v2/paths/{pathId}/sessions/{sessionId}/user-stats

Behavior changes

How to identify users in v2

A key update in v2 is the standardized method for identifying users. For improved security and consistency, you must now use the user's unique internal ID when referencing a user.

If you already have the internal ID, you can use it directly.
If you only have the user's email address, you'll need to fetch their internal ID first.

To get the user ID based on their email address:

Retrieve and cache all users:
Call List all users to retrieve the full list of users in your organization. To ensure your application is performant, this data should be stored in a local database or cache that is updated periodically.
Find the user and get their ID:
Find the user object where the mail field matches the email you are searching for.
Copy the value of their _id. This is the internal ID.

Input changes

This section details the specific alterations to the input requirements between API versions.

API v1 input example

curl --location -g 'https://{{host}}/api/v1/paths/sessions/60ad14abc2615a51213dbce9/stats/[email protected]?company={{company}}&apiKey={{apiKey}}'

API v2 input example

curl --request GET \
     --url https://app.360learning.com/api/v2/paths/507f1f77bcf86cd799439011/sessions/507f1f77bcf86cd799439011/user-stats \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json'

Main input differences

Change type	API v1	API v2
Modified Query parameters	`completedBefore` / `completedAfter` (Optional): Timestamp filters, in the format`YYYY-MM-DDTHH:mm:ss.sssZ`.	`completedAt` (Optional): Modified name, functionality, syntax, and date format. Now, this single filter combines the functionalities of `completedAtBefore` and `completedAtAfter`. It filters stats by completion date range using the LHS bracket notation. The date format is now `YYYY-MM-DD`.
Modified Path parameters	`userEmailOrId` (Path parameter, Required): Could be the email or the ID of the user. This parameter email was part of the URL path.	`userId` (Optional): user's internal ID. An email is no longer accepted here, and `userId` has to be passed through a query param. See Behavior changes (section above) for how to get the ID from an email.

Output changes

This section details the specific alterations to the successful output returned between API versions.

API v1 output example

{
  "progress": 25,
  "score": 0,
  "status": "onTime",
  "completedAt": null,
  "detailedStatus": {
    "type": "unsuccessful"
  },
  "result": "unsuccessful",
  "globalTime": 12450
}

API v2 output example

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "progress": 0,
    "status": {
      "type": "awaitingCorrection"
    },
    "timeSpent": 0,
    "userId": "507f1f77bcf86cd799439011",
    "completedAt": "2025-07-01T08:17:42.042Z",
    "score": 0,
    "enrolledAt": "2025-07-01T08:17:42.042Z",
    "unenrolledAt": "2025-07-01T08:17:42.042Z",
    "certificateId": "507f1f77bcf86cd799439011",
    "selfEnrolled": true,
    "startedAt": "2025-07-01T08:17:42.042Z",
    "dueDate": "2025-07-01T08:17:42.042Z"
  }
]

Main output differences

Change type	API v1	API v2
Modified Output property	`globalTime`: Time spent (in millis) by the learner on this path session.	`timeSpent`: (Required) Time spent (in millis) by the learner on this path session.
Modified Output property	`detailedStatus`: Detailed status of the user in the path session.	`status`: (Required) Detailed status of the user in the path session.
Added Output property		`enrolledAt` : (Required) date of enrollment of the learner in this path session,in the format`YYYY-MM-DDTHH:mm:ss.sssZ`
Added Output property		`unenrolledAt` : (Optional) date of unenrollment of the learner in this path session,in the format`YYYY-MM-DDTHH:mm:ss.sssZ`
Added Output property		`selfEnrolled` : (Required) indicate whether the learner self-enrolled to this path session or not.
Added Output property		`certificateId` : (Optional) The ID of the certificate obtained by the user in the session.

Key changes

getUsersPathSessionStats migration

Documentation links

Endpoint mapping

Input changes

API v1 input example

API v2 input example

Main input differences

Output changes

API v1 output example

API v2 output example

Main output differences

getUserPathSessionStats migration

Documentation links

Endpoint mapping

Behavior changes

How to identify users in v2

Input changes

API v1 input example

API v2 input example

Main input differences

Output changes

API v1 output example

API v2 output example

Main output differences

`getUsersPathSessionStats` migration

`getUserPathSessionStats` migration