Dashboards and insights
A dashboard is a set of charts over the trial's data, each segment summarising one data type in one stage (or a wearable measure) across participants. Insights are AI-written summaries of a participant or of the whole trial, where the feature is enabled for your team.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/trials/<trialId>/dashboards |
The trial's dashboards, as {"dashboards": [...]}, without data. |
POST |
/trials/<trialId>/dashboards |
Create a dashboard. Needs trial.admin. |
GET |
/trials/<trialId>/dashboards/<dashboardId> |
A dashboard with its segments' data computed. |
PUT |
/trials/<trialId>/dashboards/<dashboardId> |
Update a dashboard. Needs trial.admin. |
DELETE |
/trials/<trialId>/dashboards/<dashboardId> |
Delete a dashboard. Needs trial.admin. |
GET |
/trials/<trialId>/insights |
The latest trial insights. |
POST |
/trials/<trialId>/insights/refresh |
Generate fresh trial insights. |
GET |
/trials/<trialId>/participants/<participantId>/insights |
The latest insights about a participant. |
POST |
/trials/<trialId>/participants/<participantId>/insights/refresh |
Generate fresh ones. |
Reading a dashboard needs trial.readParticipantStudyData; insights need trial.readInsights (both implied by trial.read).
Dashboards
POST /trials/<trialId>/dashboards and PUT …/<dashboardId> take a name (2–100 characters) and segments, each:
| Field | Type | Notes |
|---|---|---|
id |
string | Any identifier unique within the dashboard. |
dataset |
stage, hardware |
Study data (the default) or wearable data. |
stage |
stage _id |
For stage: which stage. |
dataType |
data type _id |
For stage: which field. |
hardwareKey |
string | For hardware: steps, activeCalories, distance, averageHeartRate or averageStress. |
GET …/<dashboardId> returns the dashboard with each segment filled in with a displayType and data, chosen from the field's format: numericSummary for numbers and wearable measures (count, total, avg, min, max); lineChart for a number in a recurring stage (x occurrence numbers, y averages); barChart for a choice in a recurring stage (x occurrences, ys a count series per option); pieChart for a choice otherwise (a count per option).
Insights
GET returns {"insights": {"_id", "createdAt", "items": [...]}} — the most recently generated set — or {"insights": null} if none has been generated yet. POST …/refresh generates a new set now and returns it in the same shape. Insights are only generated when the trial's participantInsightsEnabled / trialInsightsEnabled settings are on and your team has the feature; otherwise these endpoints answer 403.