Caliper API
Learning analytics and activity tracking
Overview
Caliper tracks what students do in your app: activities started, completed, time spent, and outcomes achieved.
It's the analytics layer that powers dashboards, reports, and learning insights.
Timeback uses a custom Caliper profile with specialized event types for educational apps.
External Documentation
| Resource | Link |
|---|---|
| Official API Docs | Caliper API Docs |
| Specification | 1EdTech Caliper v1.2 |
Key Concepts
| Concept | Description |
|---|---|
| Event | A record of something that happened (activity completed, time spent, etc.) |
| Actor | The student performing the action (includes OneRoster user ID and email) |
| Object | What the student interacted with (activity, course, assessment) |
| Generated | The outcome or metrics produced (XP earned, score, time spent) |
Common Use Cases
- Track activity completion: Record when students finish quizzes, lessons, or activities
- Measure time spent: Track active and inactive learning time
- Calculate XP: Send XP earned based on performance and accuracy
- Power analytics: Feed data to dashboards and learning insights
Essential Event Types
| Event Type | Purpose |
|---|---|
ActivityEvent | Record activity completion with score, XP, and mastery metrics |
TimeSpentEvent | Track how much time students spend learning (active vs inactive) |
Examples
Emit ActivityEvent
Request
curl -X POST $TIMEBACK_CALIPER_URL/ims/caliper/v1p2/events \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sensor": "https://your-app.com", "sendTime": "2025-11-22T10:15:00Z", "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p2", "data": [{ "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2", "id": "urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594", "type": "ActivityEvent", "profile": "TimebackProfile", "eventTime": "2025-11-22T10:15:00Z", "action": "Completed", "actor": { "id": "https://api.alpha-1edtech.ai/ims/oneroster/rostering/v1p2/users/student-123", "type": "TimebackUser", "email": "student@example.com" }, "object": { "id": "activity-123", "type": "TimebackActivityContext", "subject": "Math", "app": { "name": "Math App" }, "activity": { "id": "activity-123", "name": "Multiplication Quiz" } }, "generated": { "id": "metrics-123", "type": "TimebackActivityMetricsCollection", "attempt": 1, "items": [ { "type": "xpEarned", "value": 150 }, { "type": "totalQuestions", "value": 10 }, { "type": "correctQuestions", "value": 9 } ] } }] }'const event = { '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2', id: `urn:uuid:${crypto.randomUUID()}`, type: 'ActivityEvent', profile: 'TimebackProfile', eventTime: new Date().toISOString(), action: 'Completed', actor: { id: `${TIMEBACK_API_URL}/ims/oneroster/rostering/v1p2/users/student-123`, type: 'TimebackUser', email: 'student@example.com', }, object: { id: 'activity-123', type: 'TimebackActivityContext', subject: 'Math', app: { name: 'Math App' }, activity: { id: 'activity-123', name: 'Multiplication Quiz' }, }, generated: { id: 'metrics-123', type: 'TimebackActivityMetricsCollection', attempt: 1, items: [ { type: 'xpEarned', value: 150 }, { type: 'totalQuestions', value: 10 }, { type: 'correctQuestions', value: 9 }, ], },}await fetch(`${TIMEBACK_CALIPER_URL}/ims/caliper/v1p2/events`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ sensor: 'https://your-app.com', sendTime: new Date().toISOString(), dataVersion: 'http://purl.imsglobal.org/ctx/caliper/v1p2', data: [event], }),})