​
Teacher Tools Analytics API

Route: POST /api/groups/teacher-tools
Get analytics data for teacher tools usage by students within a group, including dynamic metrics based on available tool usage data 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

ParameterTypeRequiredDefaultDescription
startDatestringNo2025-01-01T00:00:00.000ZStart date for analytics period (ISO 8601 format)
endDatestringNoCurrent dateEnd date for analytics period (ISO 8601 format)
studentsbooleanNofalseWhether to return student-level data (true) or group-level data (false)

​
Response Format

​
Group-Level Data (students=false)

Returns aggregated teacher tools 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": "Lesson Plans Created",
          "value": 12
        },
        {
          "title": "Assignments Generated",
          "value": 34
        },
        {
          "title": "Grade Reports Accessed",
          "value": 89
        },
        {
          "title": "Curriculum Tools Used",
          "value": 67
        }
      ]
    }
  ]
}

​
Student-Level Data (students=true)

Returns individual student teacher tools 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": "Lesson Plans Created",
          "value": 1
        },
        {
          "title": "Assignments Generated",
          "value": 3
        },
        {
          "title": "Grade Reports Accessed",
          "value": 8
        },
        {
          "title": "Curriculum Tools Used",
          "value": 5
        }
      ]
    }
  ]
}

​
Data Fields Explained

​
Teacher Tools Metrics

The teacher tools endpoint returns dynamic metrics based on the specific tools being tracked. Common metrics may include:
  • Lesson Plans Created: Number of lesson plans generated using teacher tools
  • Assignments Generated: Number of assignments created through teacher tools
  • Grade Reports Accessed: Number of times grading tools were accessed
  • Curriculum Tools Used: Usage count of curriculum-related tools
Note: The exact metrics returned will vary based on which teacher tools are being used and tracked within your group. All available metrics for the selected time period will be included in the response.

​
Additional Fields

  • numStudentsUsed (Group-level only): Number of unique students who used teacher tools 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
  • Metrics are dynamically generated based on available teacher tools data
  • If a metric doesn’t exist for a particular time period, it will show a value of 0