Storyboard Usage Report

Endpoint used to request the generation of the Storyboard Usage 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/storyboard-usage?month=6&year=2026' \
  --header 'Authorization: Bearer <token>' \
  --header 'Cache-Control: no-cache, no-store, must-revalidate'

Response Example (queued job)

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

The results.id field identifies the queued report job.

Response Example (cache hit)

If a file was already generated recently for the same institution, month, and year, the API does not generate a new file. It resends the notification with the existing download link and returns:

{
  "results": {
    "cached": true
  }
}

---

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
month	number	Reporting month (1–12). Filters views and likes in the given month.	Yes
year	number	Reporting year (1900–2100).	Yes

---

Response description

Key	Type	Description
results	object	Async publish result or cache indicator.
results.id	string	Message ID of the queued report job (when a new job is created).
results.cached	boolean	true when the report URL was reused from cache and the notification was resent.

---

Async flow

1. Client calls this endpoint with JWT, month, and year.
2. If a report was already generated recently for the same institution, month, and year, the API resends the notification and returns { cached: true }.
3. Otherwise, the report is generated asynchronously as an .xlsx file.
4. The requester receives push and/or email with the download URL.

Typical processing time depends on institution size (often seconds to a few minutes).

---

Data scope

The report lists user interactions (views and likes/dislikes) with storyboards belonging to the institution during the selected month and year. Each row represents one user who interacted with one storyboard in the period.

---

Excel columns

Header	Description
Storyboard	Storyboard title
Nome Completo (Usuário)	User full name
E-mail	User email
CPF	User tax ID (CPF), when registered
CNPJ	Company tax ID (CNPJ), when registered
Like	Like count in the period
Dislike	Dislike count in the period
Completed	Sim if the user viewed all stories in the storyboard; otherwise Não
Views (Enrolled)	View progress as viewed/total (e.g. 3/5)
Updated	Last interaction timestamp (view or like/dislike) in the period
Data de início	First interaction timestamp in the period
Data de Término	Last view timestamp when Completed = Sim; otherwise empty

---

Error responses

HTTP	Code	When
400	invalid_argument	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	Report generation failure

Example:

{
  "code": "invalid_argument",
  "message": "Invalid month. Must be between 1 and 12",
  "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.