Course Comments and Evaluations Report

Endpoint used to request the generation of the Course Comments and Evaluations report for an institution. Processing is asynchronous: the API returns immediately after queueing the job; the requester receives the download link via in-app notification or email when the file is ready.

Note: This endpoint is served by Toolzz LXP API (Encore reports-api), not by the institution monolith domain. Use the LXP API base URL (e.g. https://lxp.prod.api.toolzz.media).

Warning: institutionId and userId are taken from the JWT. The report is delivered only to the authenticated user who requested it.

Request Example

curl --request GET \
  --url 'https://lxp.prod.api.toolzz.media/institution/reports/course-evaluations?course_ids=1124394,1641736,1030165&month=5&year=2026' \
  --header 'Authorization: Bearer <token>' \
  --header 'Cache-Control: no-cache, no-store, must-revalidate'

Response Example

{
  "results": {
    "id": "abc123-def456-ghi789"
  }
}

The results.id field is the Pub/Sub message identifier for the async job (Encore may expose it as messageId depending on version).

---

Request description

Access Token

Parameter	Type	Description	Required
Authorization	String	JWT access token (Bearer <token>). Must include institutionId, userID, and subdomain.	Yes

URL Parameters (Query)

Parameter	Type	Description	Required
course_ids	string	Comma-separated course IDs (positive integers). At least one course is required. Only evaluations for the selected courses are included.	Yes
month	number	Reporting month (1–12). Filters course evaluations submitted in the given month.	Yes
year	number	Reporting year (1900–2100).	Yes

---

Response description

Key	Type	Description
results	object	Async publish result from the report generation topic.
results.id	string	Message ID of the queued report job.

---

Async flow

1. Client calls this endpoint with JWT, course_ids, month, and year.
2. Encore runs an analytical query on Redshift and publishes an event to generate-report-course-evaluations-topic.
3. A worker generates the .xlsx, uploads it to object storage, and calls the monolith notification API with typeReport=course-evaluations.
4. The requester receives push and/or email with the public download URL.

Typical processing time depends on institution size and the number of selected courses (often seconds to a few minutes).

---

Data scope

The report lists course evaluations (avaliacoes_curso) submitted by users for the selected courses during the given month and year. Each row represents one evaluation response. The instructor rating column shows the average rating given by the same user to instructors in that course (avaliacoes_instrutor), when available.

Courses must belong to the institution from the JWT (institutionId).

---

Excel columns

Header	Description
ID Instituição	Institution ID
ID Usuário	User ID
Nome	User full name
Email	User email
ID Curso	Course ID
Título do Curso	Course title
Data de Resposta	Evaluation submission date/time (DD/MM/YYYY às HH:MM:SS)
Classificação Curso (estrelas)	Course star rating
Comentário	Free-text comment
Avaliação ao Professor	Average instructor rating by the same user in the course (when available)

---

Error responses

HTTP	Code	When
400	invalid_argument	Missing or invalid course_ids, invalid month or year, or invalid JWT claims
401	unauthenticated	Missing or invalid JWT
429	—	Rate limit (60 requests/minute per institution on reports-api)
500	internal	Query or worker failure (check Encore traces)

Example:

{
  "code": "invalid_argument",
  "message": "Invalid course_ids. At least one course is required.",
  "details": null
}

---

Security

• Requires valid JWT (auth: true).
• Data is scoped to the institution from the token.
• Report file URL is sent only to the user who requested it (userId from JWT).
• HTTPS/TLS for all environments.