Use the Hatz Learn reporting API to add portfolio, tenant, learner, course, and completion data to your own reporting systems. For example, an MSP can export one row per learner and course to identify who has and has not completed assigned training.

For endpoint parameters and response schemas, see the Hatz Learn Reporting API documentation.

Before you start

Create a Hatz API key and send it in the X-API-Key header. See API Keys.
The key uses the owner's current user roles, permissions, tenant scope, and account-team access. It does not have separate permissions.
Use a dedicated reporting user when possible. Store the key securely and do not share or commit it.

Required permissions

Reading reports requires View Academy Team Progress. Exporting requires both View Academy Team Progress and Export Academy Reports in the same company scope.

The built-in MSP roles with portfolio-wide reporting access are:

Primary Admin
Admin
Compliance Manager

Tenant Manager does not include Hatz Learn reporting access by default. A built-in Client Admin has reporting permission for the assigned company only. Company-level permission does not become MSP-wide portfolio permission.

For least-privilege portfolio access, an MSP can keep the reporting user's normal MSP role and attach an MSP-scoped permission group containing only the two reporting permissions.

Choose the right API report

Portfolio: Retrieve aggregate MSP metrics or one metric row per authorized tenant.
Tenant summary: Retrieve aggregate metrics for one company.
Learners: Retrieve each learner's applicable, enrolled, and completed course totals, then open a learner for course-by-course detail.
Courses: Retrieve enrollment and completion coverage for each course, then open a course for learner-by-learner status.
CSV export: Generate a portfolio summary, learner summary, course summary, or activity-detail report for current reporting coverage.

CSV report types

portfolio_summary: One row per active authorized tenant. Do not include tenant_id.
learner_summary: One row per learner across the authorized portfolio. Do not include tenant_id.
course_summary: One row per course for a single tenant. tenant_id is required.
activity_detail: One row per current eligible learner-course pair with active access for the authorized portfolio or one specified tenant.

Export completed and incomplete learners

Send this request to export activity across every tenant the key owner is authorized to report on:

curl --request POST \
  --url 'https://ai.hatz.ai/v1/academy/reporting/exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_HATZ_API_KEY' \
  --data '{
    "report_type": "activity_detail"
  }'

To export one tenant, add its Hatz tenant UUID:

{
  "report_type": "activity_detail",
  "tenant_id": "00000000-0000-0000-0000-000000000000"
}

The JSON response contains filename, csv, and row_count. Save the csv string using the supplied filename. Filter the CSV's Status column for completed to find completions and for not_enrolled, not_started, or in_progress to find remaining work.

The export excludes historical course versions, ineligible learner-course pairs, revoked access, and retired records. Use the learner or course detail endpoints when you need those historical or revoked records.

The synchronous exporter supports up to 100 tenants and 5,000 rows. Contact Hatz Support if you need a larger export.

Troubleshooting

401 Unauthorized: The API key is missing, invalid, expired, or revoked. Confirm the X-API-Key header.
404 Not Found: The requested record might not be in the key owner's permitted scope, or Hatz Learn reporting might not be available to that user identity.
The portfolio contains no tenants: The key owner has no company in scope for View Academy Team Progress. Confirm MSP-scoped reporting permission and account-team access.
Summary metrics show 0/0: Check whether the portfolio contains the tenant. If it does, the company might legitimately have no currently eligible learners or applicable published courses. Zero alone does not prove a permission problem.
can_export is false: The key owner does not have both reporting permissions for a company in the requested scope. Creating another key for the same user will not change the result.
403 Forbidden on export: No exportable company is available in the requested scope.
422 Unprocessable Entity: Check the report type and tenant_id combination, query values, and synchronous export limits.

A company whose Learn switch is off can still return historical reporting data as read-only, while current coverage is unavailable. Raw or historical enrollment totals can differ from current coverage because ineligible learners and non-applicable course pairs are excluded from current denominators.

Export Hatz Learn Reporting Through the API