Timeback Activity and Time Events - Timeback Docs (Beta)

This page applies to integrations assigned the direct Caliper metrics contract. Send an envelope to POST /caliper/event on your Caliper base URL. These event types are not accepted by the Partner Events API at /events/1.0.

Envelope

Field	Requirement
`sensor`	URL identifying your registered event producer
`sendTime`	UTC ISO 8601 send timestamp
`dataVersion`	Exactly `http://purl.imsglobal.org/ctx/caliper/v1p2`
`data`	Nonempty array of events; use a different event ID for each event

Each event requires id, type, profile, actor, action, object, and eventTime. Use profile: "TimebackProfile" and an event ID in urn:uuid: form. Use the standard Caliper @context value; the schema supplies it when absent.

User and activity context

Object	Required fields	Optional fields
`actor`	`id` URL, `type: "TimebackUser"`, valid `email`	`name`, `role`, `extensions`
`object`	`id` URL, `type: "TimebackActivityContext"`, `subject`, `app`	`course`, `activity`, `process`
`object.app`	`name`	`id` URL, `extensions`
`object.course`	`name`, when the course object is supplied	`id` URL, `extensions`
`object.activity`	`name`, when the activity object is supplied	`id` URL, `extensions`

Allowed roles are student, teacher, admin, and guide. Allowed subjects are Reading, Language, Vocabulary, Social Studies, Writing, Handwriting, Science, FastMath, Math, None, and Other. Use the student’s Timeback user URL and the course URL assigned to your integration. The schema permits a course without an ID, but downstream course resolution can require it. For activity events destined for the TimebackProfile analytics worker, set object.process to true. It is a processing instruction, not a completion percentage. Confirm your assigned consumer before applying it to another platform.

ActivityEvent

Set type to ActivityEvent and action to Completed. generated requires an ID URL, type TimebackActivityMetricsCollection, and an items array.

Metric type	Meaning
`xpEarned`	XP supplied by the producer
`totalQuestions`	Number of questions represented by the activity
`correctQuestions`	Number of correct questions represented by the activity
`masteredUnits`	Number of mastered units represented by the activity

Each item contains a numeric value; item and collection extensions are optional. The schema does not infer question counts, compute correctness, or verify a mastery decision. Supply values that match the agreed measurement rule for your app. action: "Completed" describes an activity. It does not mean that the course is complete.

TimeSpentEvent

Set type to TimeSpentEvent and action to SpentTime. generated requires an ID URL, type TimebackTimeSpentMetricsCollection, and an items array.

Field	Meaning
`items[].type`	`active`, `inactive`, `waste`, `unknown`, or `anti-pattern`
`items[].value`	Duration in seconds, at most 86,400 per item
`items[].subType`	Optional detail about the measured activity
`items[].startDate` and `endDate`	Optional UTC ISO 8601 timestamps
`items[].extensions`	Optional metadata

Send nonnegative durations that match the measured interval. The current schema enforces the upper duration bound; it does not enforce a lower bound, timestamp ordering, or equality between duration and timestamp difference. Validate these conditions in your producer. Time measurement is separate from XP measurement. Replaying an interval under a new event identity can add time again in downstream processing. Preserve the event identity for a transport retry and retain your own record of sent intervals.

Example envelope

This synthetic example records an activity and five minutes of active time. Replace its IDs, addresses, sensor, and timestamps with the values assigned to your integration.

{
  "sensor": "https://learning.example.com",
  "sendTime": "2026-09-11T15:00:00.000Z",
  "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "data": [
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:437620ad-f9c9-4a9d-9232-37676bfcf28e",
      "eventTime": "2026-09-11T15:00:00.000Z",
      "profile": "TimebackProfile",
      "actor": {
        "id": "https://api.example.com/ims/oneroster/rostering/v1p2/users/student-example",
        "type": "TimebackUser",
        "email": "learner@example.com",
        "role": "student"
      },
      "object": {
        "id": "https://learning.example.com/activities/activity-example",
        "type": "TimebackActivityContext",
        "subject": "Math",
        "process": true,
        "app": {
          "name": "Example Learning App"
        },
        "course": {
          "id": "https://api.example.com/ims/oneroster/rostering/v1p2/courses/course-example",
          "name": "Fractions"
        },
        "activity": {
          "name": "Adding fractions"
        }
      },
      "type": "ActivityEvent",
      "action": "Completed",
      "generated": {
        "id": "https://learning.example.com/metrics/activity-example",
        "type": "TimebackActivityMetricsCollection",
        "items": [
          {
            "type": "xpEarned",
            "value": 10
          },
          {
            "type": "totalQuestions",
            "value": 5
          },
          {
            "type": "correctQuestions",
            "value": 4
          },
          {
            "type": "masteredUnits",
            "value": 0
          }
        ]
      }
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:9c4a6261-26ad-4a3c-9329-466d41ebbc4d",
      "eventTime": "2026-09-11T15:00:00.000Z",
      "profile": "TimebackProfile",
      "actor": {
        "id": "https://api.example.com/ims/oneroster/rostering/v1p2/users/student-example",
        "type": "TimebackUser",
        "email": "learner@example.com",
        "role": "student"
      },
      "object": {
        "id": "https://learning.example.com/activities/activity-example",
        "type": "TimebackActivityContext",
        "subject": "Math",
        "process": true,
        "app": {
          "name": "Example Learning App"
        },
        "course": {
          "id": "https://api.example.com/ims/oneroster/rostering/v1p2/courses/course-example",
          "name": "Fractions"
        },
        "activity": {
          "name": "Adding fractions"
        }
      },
      "type": "TimeSpentEvent",
      "action": "SpentTime",
      "generated": {
        "id": "https://learning.example.com/metrics/time-example",
        "type": "TimebackTimeSpentMetricsCollection",
        "items": [
          {
            "type": "active",
            "value": 300,
            "startDate": "2026-09-11T14:55:00.000Z",
            "endDate": "2026-09-11T15:00:00.000Z"
          }
        ]
      }
    }
  ]
}

Validate and confirm

Use POST /caliper/event/validate with the same envelope to check its schema without storing it. On success, the validator returns 200 with status: "success" and message: "Request payload is valid". Ingestion returns 200 after validation and queuing. Retain its jobId. For the Caliper service, GET /jobs/{jobId}/status exposes queue state and the worker’s returnValue. Check result status and errors as well as the queue state. A completed queue job does not prove that every downstream subscriber succeeded. Do not replace an event payload by resending a changed payload under the same event ID. The Caliper service keeps the first stored event content for that ID. Corrections need the correction procedure agreed for the integration.

​Envelope

​User and activity context

​ActivityEvent

​TimeSpentEvent

​Example envelope

​Validate and confirm