Insights API

The Insights API provides session-oriented views into student learning behavior: aggregated time, waste, and XP summaries per user, paginated session lists, time-window overviews with daily trends, and per-session detail. All endpoints require Authorization: Bearer <token> and scope events.readonly.

Base prefix: https://api.alpha-1edtech.ai/insights/1.0

---

GET /insights/1.0/users/:userId

Returns aggregated time, waste, and XP insights for a student, with a per-subject breakdown. Optionally scoped to a date range.

Scope: events.readonly

Path params

Name	Description
userId	Student UUID

Query params

Name	Description	Required
startDate	Start of the date range (ISO datetime)	no
endDate	End of the date range (ISO datetime)	no

Response

200 OK:

{
  "userId": "22222222-2222-2222-2222-222222222222",
  "session": null,
  "insights": [
    {
      "type": "TIME_SUMMARY",
      "totalSeconds": 3600,
      "activeSeconds": 3000,
      "wasteSeconds": 400,
      "inactiveSeconds": 200,
      "wastePercentage": 11,
      "totalXpEarned": 450,
      "factCount": 12
    }
  ],
  "bySubject": [
    {
      "subject": "Math",
      "activeSeconds": 2000,
      "wasteSeconds": 200,
      "inactiveSeconds": 100,
      "xpEarned": 300
    }
  ]
}

Example

curl "https://api.alpha-1edtech.ai/insights/1.0/users/22222222-2222-2222-2222-222222222222?startDate=2026-01-01T00:00:00Z&endDate=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

---

GET /insights/1.0/users/:userId/sessions

Returns a paginated list of learning sessions for a student. Sessions represent continuous activity periods within an app.

Scope: events.readonly

Path params

Name	Description
userId	Student UUID

Query params

Name	Description	Required
applicationId	Filter by application sourcedId	no
startedAfter	Only sessions started after this ISO datetime	no
startedBefore	Only sessions started before this ISO datetime	no
limit	Maximum records per page (default 20, max 100)	no
offset	Number of records to skip (default 0)	no

Response

200 OK:

{
  "sessions": [
    {
      "id": "SESSION_UUID",
      "applicationId": "your-app",
      "startedAtTime": "2026-01-15T10:00:00.000Z",
      "endedAtTime": "2026-01-15T11:00:00.000Z",
      "durationInSeconds": 3600,
      "wasteDurationInSeconds": 400,
      "wastePercentage": 11
    }
  ],
  "offset": 0,
  "limit": 20,
  "total": 5
}

Example

curl "https://api.alpha-1edtech.ai/insights/1.0/users/22222222-2222-2222-2222-222222222222/sessions?startedAfter=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

---

GET /insights/1.0/users/:userId/overview

Returns an aggregate overview of a student's sessions within a time window, including daily trend data and waste breakdown by category.

Scope: events.readonly

Path params

Name	Description
userId	Student UUID

Query params

Name	Description	Required
startedAfter	Start of the overview window (ISO datetime, required)	yes
startedBefore	End of the overview window (ISO datetime, required)	yes
targetTimezone	IANA timezone for daily bucketing (default UTC)	no

Response

200 OK:

{
  "summary": {
    "totalDurationInSeconds": 18000,
    "totalWasteDurationInSeconds": 2000,
    "wastePercentage": 11
  },
  "trend": {
    "buckets": [
      {
        "startedAtTime": "2026-01-15T00:00:00.000Z",
        "endedAtTime": "2026-01-15T23:59:59.000Z",
        "totalDurationInSeconds": 3600,
        "wasteDurationInSeconds": 400,
        "wastePercentage": 11
      }
    ]
  },
  "breakdown": {
    "levels": [
      { "level": "distraction", "durationInSeconds": 2000, "wastePercentage": 100 }
    ]
  }
}

400 Bad Request — Missing required parameters.

Example

curl "https://api.alpha-1edtech.ai/insights/1.0/users/22222222-2222-2222-2222-222222222222/overview?startedAfter=2026-01-01T00:00:00Z&startedBefore=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

---

GET /insights/1.0/sessions/:sessionId

Returns detailed information about a single session, including session-level insights.

Scope: events.readonly

Path params

Name	Description
sessionId	Session UUID

Query params

Name	Description	Required
limit	Maximum insight records per page (default 20, max 100)	no
offset	Number of insight records to skip (default 0)	no

Response

200 OK:

{
  "session": {
    "id": "SESSION_UUID",
    "applicationId": "your-app",
    "userId": "22222222-2222-2222-2222-222222222222",
    "startedAtTime": "2026-01-15T10:00:00.000Z",
    "endedAtTime": "2026-01-15T11:00:00.000Z",
    "durationInSeconds": 3600,
    "wasteDurationInSeconds": 400,
    "wastePercentage": 11,
    "loggedOut": true,
    "requiresHeartbeat": true,
    "processInsights": false,
    "insights": []
  },
  "insights": [
    { "type": "distraction", "durationInSeconds": 400 }
  ],
  "offset": 0,
  "limit": 20,
  "total": 1
}

404 — Session not found.

Example

curl "https://api.alpha-1edtech.ai/insights/1.0/sessions/SESSION_UUID" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"