Tests Analytics API

Route: POST /api/groups/tests

Get analytics data for test usage by students within a group, including tests created, questions made, answer accuracy, and chat interactions with optional student-level breakdowns.

Authentication

This endpoint requires authentication using an API key. Header Required:

x-api-key: YOUR_API_KEY

Parameters

Query Parameters

Parameter	Type	Required	Default	Description
`startDate`	string	No	`2025-01-01T00:00:00.000Z`	Start date for analytics period (ISO 8601 format)
`endDate`	string	No	Current date	End date for analytics period (ISO 8601 format)
`students`	boolean	No	`false`	Whether to return student-level data (`true`) or group-level data (`false`)

Response Format

Group-Level Data (students=false)

Returns aggregated test analytics for the entire group.

{
  "success": true,
  "reports": [
    {
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-07T23:59:59.999Z",
      "numStudentsUsed": 25,
      "data": [
        {
          "title": "Tests Made",
          "value": 28
        },
        {
          "title": "Questions Made",
          "value": 312
        },
        {
          "title": "Questions Answered Correctly",
          "value": 1847
        },
        {
          "title": "Questions Answered Incorrectly",
          "value": 423
        },
        {
          "title": "Chat Questions Asked",
          "value": 156
        }
      ]
    }
  ]
}

Student-Level Data (students=true)

Returns individual student test analytics.

{
  "success": true,
  "reports": [
    {
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-07T23:59:59.999Z",
      "studentName": "John Doe",
      "studentId": "user_123456",
      "data": [
        {
          "title": "Tests Made",
          "value": 2
        },
        {
          "title": "Questions Made",
          "value": 24
        },
        {
          "title": "Questions Answered Correctly",
          "value": 89
        },
        {
          "title": "Questions Answered Incorrectly",
          "value": 16
        },
        {
          "title": "Chat Questions Asked",
          "value": 8
        }
      ]
    }
  ]
}

Data Fields Explained

Test Metrics

Tests Made: Number of tests created by students
Questions Made: Total number of test questions created
Questions Answered Correctly: Number of test questions answered correctly
Questions Answered Incorrectly: Number of test questions answered incorrectly
Chat Questions Asked: Number of chat questions asked related to test content

Additional Fields

numStudentsUsed (Group-level only): Number of unique students who used test features
studentName (Student-level only): Display name of the student
studentId (Student-level only): Unique identifier for the student

Error Responses

403 Unauthorized

Returned when API key is missing or invalid.

{
  "error": "Unauthorized"
}

Causes:

Missing x-api-key header
Invalid API key
API key not associated with a valid group plan

400 Bad Request

Returned when required parameters are missing.

{
  "error": "Missing params"
}

Notes

Reports are automatically sorted by start date in ascending order
Date ranges are inclusive of both start and end dates
All timestamps should be in ISO 8601 format

​Tests Analytics API

​Authentication

​Parameters

​Query Parameters

​Response Format

​Group-Level Data (students=false)

​Student-Level Data (students=true)

​Data Fields Explained

​Test Metrics

​Additional Fields

​Error Responses

​403 Unauthorized

​400 Bad Request

​Notes