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):
| Parameter | Type | Required | Description |
| team | string | No | Filters results for a specific team |
| limit | integer | No | Maximum number of results per page (min: 1, max: 1000) |
| page | integer | No | Results page to retrieve (default: 1) |
Response structure
Each user record in the response contains the following fields:
| Field | Description |
| User's email address | |
| assigned_total | Total number of modules assigned across all services |
| completed_total | Total number of modules completed across all services |
| completion_rate_total | Overall completion percentage (0–100), rounded to 2 decimal places |
| services.awareness | Details of modules assigned, completed, and percentage for the Awareness service |
| services.channel | Details of modules assigned, completed, and percentage for the Channel service |
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
| HTTP Code | Error Code | Description |
| 400 | EXT_1000 | Invalid input parameter (the message indicates which parameter and the allowed values) |
| 400 | EXT_1000 | The requested page does not exist (the message indicates the total number of available pages) |
| 404 | EXT_1003 | Error retrieving data |
| 422 | EXT_1004 | The specified team does not exist in the company |
| 500 | EXT_1001 | Token expired or invalid |
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.