List Batch Student Grades

This endpoint returns the grades of every student enrolled in one or more courses in Toolzz LXP, in a single paginated call. It is intended for bulk grade extraction (e.g. institutional reports or data exports) and replaces per-student lookups with a single batch query.

Note: Only users with admin privilege (privilegio_id = 2) can call this endpoint. All course_ids must belong to the institution authenticated via JWT, otherwise the request is rejected.

Note: Responses are cached server-side for 5 minutes, keyed by the requested course_ids/page/per_page combination. The response also carries Cache-Control: private, max-age=300.

Request Example

curl --request GET \
  --url 'https://kong.api.toolzz.com.br/api/v2/content/score/user?course_ids[]=101&course_ids[]=102&page=1&per_page=3' \
  --header 'Authorization: Bearer <token>'

Response Example

{
  "data": [
    {
      "user_id": 90000001,
      "user_name": "Aluno Perf 90000001",
      "email": "perf_90000001@seed.test",
      "school_id": 88060553,
      "school_name": "h1u1",
      "courses": [
        {
          "course_id": 1085263,
          "course_name": "Curso trilha desempenho 03",
          "class_id": [100013390],
          "ratings": [
            {
              "content_id": 6783779,
              "content_type": 9,
              "content_name": "Avaliação 02",
              "percentage": 9.59
            }
          ],
          "average_rating": 9.59,
          "course_complete": 0,
          "enrollment_date": "30/06/2026 13:16:11",
          "completion_date": null
        }
      ]
    }
  ],
  "meta": {
    "total": 50001,
    "current_page": 1,
    "per_page": 3,
    "last_page": 16667
  },
  "message": "Notas recuperadas com sucesso."
}

Response Example (no students enrolled)

{
  "data": [],
  "meta": {
    "total": 0,
    "current_page": 1,
    "per_page": 100,
    "last_page": 1
  },
  "message": "Nenhum aluno matriculado nos cursos informados."
}

Request description

Access Token

Parameter	Type	Description	Required
`Authorization`	String	Access token (“Bearer” must be before the token). Admin role required (`privilegio_id = 2`).	Yes

URL Parameters (Query)

Parameter	Type	Description	Required
`course_ids`	int[]	Course IDs to extract grades for. Sent as a repeated query parameter (`course_ids[]=1&course_ids[]=2`), not comma-separated. Between 1 and 30 IDs, all owned by the authenticated institution.	Yes
`page`	int	Page number for the paginated list of students. Default: `1`.	No
`per_page`	int	Number of students per page. Maximum `200`. Default: `100`.	No

Response description

Key	Type	Description
`data`	array	Page of students matching the requested courses.
`data.user_id`	number	Student user ID.
`data.user_name`	string	Student full name.
`data.email`	string	Student email address.
`data.school_id`	number	ID of the student’s school.
`data.school_name`	string	Name of the student’s school.
`data.courses`	array	Courses (from the requested `course_ids`) the student is enrolled in.
`data.courses.course_id`	number	Course identifier.
`data.courses.course_name`	string	Course title.
`data.courses.class_id`	array	Class ID(s) linked to the course (empty array if the course has no class).
`data.courses.ratings`	array	Graded content (assessments and deliverables) found for this student in this course.
`data.courses.ratings.content_id`	number	Content identifier.
`data.courses.ratings.content_type`	number	Content type: `9` = assessment, `10` = deliverable.
`data.courses.ratings.content_name`	string	Content title.
`data.courses.ratings.percentage`	number	Score obtained on this content (0–10 scale).
`data.courses.average_rating`	number	Average of `ratings.percentage` for this course. `0` when there is no graded content yet.
`data.courses.course_complete`	number	`1` if the student completed the course, `0` otherwise.
`data.courses.enrollment_date`	string \| null	Enrollment date/time (`dd/mm/YYYY HH:mm:ss`).
`data.courses.completion_date`	string \| null	Completion date/time (`dd/mm/YYYY HH:mm:ss`). `null` when the course is not complete.
`meta`	object	Pagination metadata.
`meta.total`	number	Total number of enrolled students matching the requested courses (across all pages).
`meta.current_page`	number	Current page number.
`meta.per_page`	number	Page size used.
`meta.last_page`	number	Last available page number.
`message`	string	Status message (in Portuguese), e.g. success or no students enrolled.

Error responses

Errors are returned as RFC 9457 application/problem+json (unlike other content-api endpoints, which return plain { "message": ... }).

HTTP	Situation
`400`	`course_ids` not provided, or contains no valid positive integers.
`400`	`course_ids` contains more than 30 IDs.
`400`	One or more `course_ids` do not belong to the authenticated institution.
`400`	`page` or `per_page` fails validation (e.g. `per_page` greater than 200).
`403`	Authenticated user is not an admin (`privilegio_id !== 2`).
`429`	Rate limit exceeded (60 req/min).

{
  "type": "https://kong.api.toolzz.com.br/api/v2/content/score/user",
  "title": "Request with invalid data",
  "status": 400,
  "detail": "O parâmetro course_ids é obrigatório e deve conter IDs inteiros positivos.",
  "instance": "/v2/content/score/user"
}

{
  "type": "https://kong.api.toolzz.com.br/api/v2/content/score/user",
  "title": "Request with invalid data",
  "status": 400,
  "detail": "Um ou mais course_ids não pertencem à instituição autenticada.",
  "instance": "/v2/content/score/user"
}

{
  "type": "https://kong.api.toolzz.com.br/api/v2/content/score/user",
  "title": "Forbidden",
  "status": 403,
  "detail": "Apenas administradores podem acessar este endpoint.",
  "instance": "/v2/content/score/user"
}

Security

To access this endpoint, it is necessary to send a valid access token through the authorization header (Authorization) of the request, belonging to an admin user. Additionally, the API is protected by other security measures to safeguard user data.