Reports API

A report is a high-level summary of sessions, exported as a table. The HEAT v2 API serves each report as a CSV or XLSX file that a learning record system or a spreadsheet can read.

A report definition names a set of columns. Each column reads one value from a small set of records HEAT keeps for every session, such as its date, its scenario, a trainee or a key in the session metadata. HEAT evaluates the definition when you request the download, so the file always reflects the current values. These are the same reports an instructor downloads from the Reports page of the HEAT dashboard.

A report is not a query over session data. It cannot read what the nodes of a session computed, and it cannot aggregate across sessions. Reporting is implemented by the originating session template. The template writes its key metrics into the session metadata, and a report column reads them from there. A session whose template does not do this has nothing on the session for a report to read beyond its date, scenario and users. See Assessment values in session metadata and Limitations.

For deep analysis across many sessions, build a session template that queries the sessions and produces the analysis as an artefact. See Cross-session analysis.

A report is not a raw data export either. It does not return the stored outputs of a node. Use the outputs routes in the HEAT v2 API reference for that.

Prerequisites

• A token from HEAT Auth, sent as Authorization: Bearer <token> on every call.
• The Administrator, Instructor or Developer role. Creating, updating and deleting report definitions needs Administrator or Developer.
• An offline token is accepted on every route on this page except delete, which suits a scheduled export job.

Routes

Report catalog

The catalog lists every report defined in the environment and names the default.

curl -H "Authorization: Bearer $HEAT_TOKEN" \
  "https://heat.example.com/api/v2/dashboard/reports/catalog"

{
  "reports": [
    {
      "key": "session-list",
      "name": "Session List",
      "configurationKey": "sessionList"
    }
  ],
  "defaultReport": "session-list"
}

Pass a report’s key to the download route.

Report download

The download route builds the report and returns it as a file.

curl -H "Authorization: Bearer $HEAT_TOKEN" -OJ \
  "https://heat.example.com/api/v2/dashboard/reports/download?report=session-list&format=csv&from=2026-01-01&to=2026-01-31"

The response is a file. CSV is served as text/csv and XLSX as application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. The Content-Disposition filename is {fileName}_{ddMMyyyy_HH.mm}.{csv|xlsx}, where fileName comes from the report definition and defaults to SessionList.

Rows

A Dimension is the dashboard-facing result a session publishes. A report holds one row for each user of each dimension that passes the report’s filters. A dimension with no users produces one row with empty user values.

The first line of a CSV file, and the first row of an XLSX sheet, holds the column names from the report definition.

User names and email addresses are resolved from HEAT Auth when the report is built. HEAT does not store them with session results.

Report definitions

A report definition is the set of columns and filters behind one catalog entry. Read one to learn what a report contains, or create one from your own tooling.

The definition routes are the only part of the v2 API that changes how reports behave. They control which reports exist, their columns, their filters, the filename and the default report. The row model, the file formats and the download parameters are fixed.

Definitions belong to the whole environment. A change applies at once to every caller and to the Reports page of the HEAT dashboard.

curl -H "Authorization: Bearer $HEAT_TOKEN" \
  "https://heat.example.com/api/v2/dashboard/reports/afv-all"

Create a report with POST /api/v2/dashboard/reports. Update one with PUT /api/v2/dashboard/reports/{key}. Both take the same body.

{
  "key": "afv-all",
  "name": "AFV All",
  "fileName": "AFV_Report",
  "dimensionNameFilter": "AFV Recognition",
  "setAsDefault": false,
  "replaceConfiguration": true,
  "columns": [
    {
      "columnKey": "Date",
      "name": "Date",
      "expression": "from",
      "type": "datetime",
      "format": "yyyy-MM-dd",
      "source": "scenarioInstance",
      "order": 1
    },
    {
      "columnKey": "Trainee",
      "name": "Trainee",
      "expression": "email",
      "source": "user",
      "order": 2
    },
    {
      "columnKey": "Detections",
      "name": "Detections",
      "expression": "reporting.kpis.detections",
      "type": "numeric",
      "source": "metadata",
      "order": 3
    }
  ],
  "filters": [
    {
      "filterKey": "ScenarioName",
      "expression": "scenario_type",
      "value": "AFV",
      "source": "metadata"
    }
  ]
}

The reporting.kpis.detections path is an example. The keys available under the metadata source depend on what the uploader and the session template write into the session metadata.

Deleting a report

DELETE /api/v2/dashboard/reports/{key} removes the report from the catalog and deletes its stored columns and filters. It returns 204 No Content.

curl -X DELETE -H "Authorization: Bearer $HEAT_TOKEN" \
  "https://heat.example.com/api/v2/dashboard/reports/afv-all"

An environment always keeps one report, so deleting the only report returns 409. Deleting the default report makes the first remaining report the default. An offline token cannot delete a report.

Columns

A datetime column accepts an ISO 8601 string or a Unix time in milliseconds.

Filters

A row is kept only when every filter passes.

Strings match when the result contains value, and the comparison is case-sensitive. Numbers match when they are equal. When the expression returns a list, the filter passes if any item matches.

Sources

Assessment values in session metadata

Session metadata is a JSON object stored with each session. It is the only place a report can read a value that the session itself produced.

A value reaches the session metadata in one of these ways.

Plan the keys with the session template. A report column then reads them with "source": "metadata" and a path such as reporting.kpis.detections.

Sessions processed before the template wrote a key have no value for it. The column is empty for those rows, or 0 for a numeric column, until the session is reprocessed.

Limitations

• A report reads fixed records for each session. Querying the contents of node outputs or dashboards across sessions is not available today.
• There is no aggregation, grouping, sorting or joining. A report always holds one row for each user of each dimension.
• The download parameters are limited to the date range, one user and the format. Any other selection is a filter in the report definition, and a filter can only test that a value contains or equals a constant.
• CSV and XLSX are the only output formats. The rows are not available as JSON.
• A report is built while the request waits, with one lookup for each session in the date range. There is no paging. Keep date ranges bounded for environments with many sessions.
• Report definitions are environment-wide. They cannot be scoped to a Project or to a caller.

Deep analysis across sessions belongs in a session template, not in a report. A template can query one trainee’s sessions or one kind of session, process the matches on the platform’s runners and store the analysis as a downloadable artefact. It can run on a schedule and publish a comparative dashboard from the same session. See Cross-session analysis.

Errors

Related

• APIs
• HEAT v2 API
• Cross-session analysis
• Offline tokens
• Dimensions

HEAT documentation team. Last updated 2 October 2026.