Match Games Analytics API

Route: POST /api/groups/match-games

Get analytics data for match game usage by students within a group, including games created, games played, and match accuracy 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 match game 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": "Games Made",
          "value": 42
        },
        {
          "title": "Games Played",
          "value": 186
        },
        {
          "title": "Correct Matches",
          "value": 1247
        },
        {
          "title": "Incorrect Matches",
          "value": 284
        }
      ]
    }
  ]
}

Student-Level Data (students=true)

Returns individual student match game 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": "Games Made",
          "value": 2
        },
        {
          "title": "Games Played",
          "value": 8
        },
        {
          "title": "Correct Matches",
          "value": 67
        },
        {
          "title": "Incorrect Matches",
          "value": 12
        }
      ]
    }
  ]
}

Data Fields Explained

Match Game Metrics

Games Made: Number of match games created by students
Games Played: Total number of match game sessions played
Correct Matches: Number of correct matches made during gameplay
Incorrect Matches: Number of incorrect matches made during gameplay

Additional Fields

numStudentsUsed (Group-level only): Number of unique students who used match game 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

Platform Usage API

Match games

Match Games Analytics API

Authentication

Parameters

Query Parameters

Response Format

Group-Level Data (students=false)

Student-Level Data (students=true)

Data Fields Explained

Match Game Metrics

Additional Fields

Error Responses

403 Unauthorized

400 Bad Request

Notes

​Match Games Analytics API

​Authentication

​Parameters

​Query Parameters

​Response Format

​Group-Level Data (students=false)

​Student-Level Data (students=true)

​Data Fields Explained

​Match Game Metrics

​Additional Fields

​Error Responses

​403 Unauthorized

​400 Bad Request

​Notes

Match Games Analytics API

Authentication

Parameters

Query Parameters

Response Format

Group-Level Data (students=false)

Student-Level Data (students=true)

Data Fields Explained

Match Game Metrics

Additional Fields

Error Responses

403 Unauthorized

400 Bad Request

Notes