XP System

Understand TimeBack's XP (eXperience Points) system to correctly award and track student progress across learning apps.

What XP Represents

XP is TimeBack's universal metric for tracking productive learning effort across all subjects, grades, and apps.

Core principle: 1 XP ≈ 1 minute of focused, productive learning effort from a typical student.

Key distinctions:

• XP measures effort, not progress. A student can earn XP while their mastery percentage stays flat (reviewing material) or increases (learning new material). These are separate metrics.
• XP is cumulative. Once earned, XP never decreases due to knowledge decay. Knowledge state can regress (students forget), but XP remains as a permanent record of effort.
• XP is content-intrinsic. Each piece of content has a fixed "expected XP" value that's the same for all students, regardless of how long an individual student takes.

Setting Expected XP

Every piece of content in your app (lessons, quizzes, assessments) should have an expected XP value—the amount a student earns for completing it at mastery.

How to calibrate expected XP:

1. Have a competent person complete the content correctly while being timed ("speed-running")
2. Round the time to the nearest minute—that's your expected XP
3. Do not use student averages (they include off-task time and struggling students)

Example: A lesson takes a competent adult 12 minutes to complete thoughtfully → Expected XP = 12

This approach ensures XP remains consistent across your content and aligned with TimeBack's 1 XP ≈ 1 minute baseline.

When to Award XP

Award XP when learning is verified, not when activities are merely completed.

Do not award XP for:

• Incomplete activities
• Activities completed below mastery threshold (unless using partial credit for reattempts)
• Passive consumption without verification (watching a video doesn't prove learning)

Mastery Thresholds

TimeBack uses accuracy-based mastery thresholds to determine when learning has occurred:

Below these thresholds, students haven't demonstrated mastery at the rigor required. Award 0 XP for sincere effort below threshold, or negative XP for gaming/cheating (see below).

How Much XP to Award

Use this decision table to determine XP awards based on performance and attempt number:

Bonus XP for perfect performance: Award 20-25% bonus XP when students achieve 100% accuracy on their first attempt. This incentivizes careful, focused work.

Partial credit on reattempts: When students fail initially but achieve mastery on a retry, award reduced XP. This encourages getting it right the first time while still rewarding eventual mastery.

Negative XP

Award negative XP when students demonstrate insincere effort—gaming, cheating, or deliberately rushing through content without learning.

Examples of gaming patterns:

• Rapid random guessing (answering faster than reading is possible)
• Using calculators or LLMs to avoid learning
• Systematic patterns suggesting answer-lookup
• Deliberate failure to exploit reattempt mechanics

Calibration principle: Genuine students who are trying should rarely (if ever) receive negative XP. Only penalize clear patterns of bad faith, not individual mistakes or struggling learners.

The exact negative XP amount should reflect the severity—typically -2 to -5 XP per incident.

Sending XP Events

Send XP awards to TimeBack using Caliper GradeEvent with scoreType: "XP".

Example event:

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": {
    "id": "urn:uuid:xp-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": {
      "id": "https://yourapp.com/lessons/fractions-intro",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:score-xp-id",
    "type": "Score",
    "scoreType": "XP",
    "attempt": "urn:uuid:xp-attempt-id",
    "scoreGiven": 15
  },
  "eventTime": "2024-01-15T14:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

For complete event schema details, see Caliper Events Reference.

Reading XP Data

After sending XP events, you can read back XP entries to display progress in your app or verify events were processed.

Required Scope

Request the events read scope when registering:

scope: https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.readonly

Fetch XP Entries

const response = await fetch(
  `https://platform.timeback.com/xp/1.0/users/${userId}/entries?applicationId=${process.env.TIMEBACK_APP_ID}`,
  {
    headers: { Authorization: `Bearer ${accessToken}` },
  },
);

const { entries, total, limit, offset } = await response.json();

Response Schema

{
  "entries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "value": 15,
      "userId": "student-platform-id",
      "applicationId": "your-app-id",
      "curriculumItemId": "lesson-id-if-provided",
      "sourceEventId": "caliper-event-id",
      "dateGenerated": "2024-01-15T14:30:00.000Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Query Parameters

Example: Get Today's XP

To display XP earned today, filter by date and sum the values:

async function getTodaysXP(userId: string, accessToken: string): Promise<number> {
  const today = new Date();
  today.setHours(0, 0, 0, 0);

  const params = new URLSearchParams({
    applicationId: process.env.TIMEBACK_APP_ID,
    after: today.toISOString(),
    limit: '100',
  });

  const response = await fetch(`https://platform.timeback.com/xp/1.0/users/${userId}/entries?${params}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });

  const { entries, total } = await response.json();

  // If more than 100 entries, paginate to get all
  let allEntries = entries;
  if (total > 100) {
    // Fetch remaining pages...
  }

  return allEntries.reduce((sum, entry) => sum + entry.value, 0);
}

See the API Reference for complete endpoint documentation.

Related Docs

Level 3: Caliper Events

Implementation guide for sending Caliper events, including XP awards.

Caliper Events Reference

Complete event schemas and field documentation for XP and other event types.

Authentication

Obtain OAuth credentials required for sending events and reading XP data.