> ## Documentation Index
> Fetch the complete documentation index at: https://www.studyfetch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Teacher tools

# 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

| 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 teacher tools analytics for the entire group.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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