User Progress Completion Extraction API

Purpose

Cyber Guru provides the ability to retrieve training module completion rates for each user in your organization through a REST API that returns data in JSON format, ready to be integrated into external reporting systems.

For each user, the API returns the number of modules assigned and completed, the overall completion percentage, and a breakdown by individual service (Awareness and Channel).
This guide contains the instructions and parameters for calling the service.

Scope

This information applies to the Cyber Security Awareness Cyber Guru 2.0 platform.

Prerequisites

• The customer must have the technical resources to call REST APIs.

Procedure

Cyber Guru provides two REST APIs:

Get token:

URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token

This API allows you to obtain an authorization token. Call parameters (POST method):

• client_id : ext-api
• client_secret : (provided by Cyber Guru)
• grant_type : client_credentials

Get users progress completion:

URL: https://<host>/ext/report/users-progress-completion

This allows you to get detailed training progress for each user in the company. To call the API, you need to provide the previously obtained token as a Bearer token.
The API accepts the following parameters (GET method):

Response structure

Each user record in the response contains the following fields:

The completion percentage is 0 when no modules have been assigned yet for that service.

Response examples

Basic response (without pagination):

{
  "users": [
    {
      "email": "anna.ferrari@company.com",
      "assigned_total": 20, "completed_total": 17, "completion_rate_total": 85.00,
      "services": {
        "awareness": { "assigned": 12, "completed": 11, "completion_rate": 91.67 },
        "channel":   { "assigned": 8,  "completed": 6,  "completion_rate": 75.00 }
      }
    },
    {
      "email": "marco.rossi@company.com",
      "assigned_total": 20, "completed_total": 20, "completion_rate_total": 100.00,
      "services": {
        "awareness": { "assigned": 12, "completed": 12, "completion_rate": 100.00 },
        "channel":   { "assigned": 8,  "completed": 8,  "completion_rate": 100.00 }
      }
    }
  ],
  "total_users": 2
}

Response with pagination:

{
  "users": [ { "email": "anna.ferrari@company.com", ... } ],
  "total_users": 230,
  "pagination": {
    "current_page": 1, "per_page": 10, "total_items": 230, "total_pages": 23,
    "from": 1, "to": 10, "has_next": true, "has_prev": false,
    "next_page": 2, "prev_page": null, "first_page": 1, "last_page": 23
  }
}

The fields in the pagination object have the same meaning as described for other reporting services.

Errors

Technical notes

• For datasets with many users, it is recommended to always use the limit and page parameters to avoid timeouts. The limit value should be chosen based on the size of your organization's user base on the platform.
• The returned data automatically excludes deleted, suspended, and unlicensed users, as well as users who have not yet been assigned any modules.

Cyber Guru is available to support customers during the configuration and testing phase in the staging environment and, after successful testing, in the production environment.