Caliper - Timeback Docs (Beta)

The Caliper client builds and sends learning events. Available routes, payload transformation, response fields, validation, and historical queries depend on the selected platform. Start with Event Contracts.

Platform capabilities

Client platform	Default submission path	Query, validation, and job methods
`BEYOND_AI`	`/caliper/event`	Legacy `validate`, `list`, `get`, `stream`, and job polling paths
`LEARNWITH_AI`	`/caliper/v1p2`	Send-only in this client; unsupported methods raise an error

The default platform is BEYOND_AI. LEARNWITH_AI applies a destination-specific event transformation before submission. Changing only the base URL does not prove that the selected paths or payload schema match another API. The Partner Events API at /events/1.0 has a separate contract.

Installation

npm install @timeback/caliper

pip install timeback-caliper

Send an activity

Run credentialed client code on a trusted backend. These examples explicitly select the legacy contract and supply synthetic identities. Replace them with assigned user, course, and app values.

import { CaliperClient } from '@timeback/caliper'

const client = new CaliperClient({
  platform: 'BEYOND_AI',
  env: 'staging',
  auth: {
    clientId: process.env.CALIPER_CLIENT_ID!,
    clientSecret: process.env.CALIPER_CLIENT_SECRET!,
  },
})

const result = await client.events.sendActivity('https://learning.example.com', {
  id: 'urn:uuid:437620ad-f9c9-4a9d-9232-37676bfcf28e',
  eventTime: '2026-09-11T15:00:00.000Z',
  actor: {
    id: 'https://api.example.com/ims/oneroster/rostering/v1p2/users/student-example',
    type: 'TimebackUser',
    email: 'learner@example.com',
  },
  object: {
    id: 'https://learning.example.com/activities/fractions',
    type: 'TimebackActivityContext',
    subject: 'Math',
    app: { name: 'Example Learning App' },
    course: {
      id: 'https://api.example.com/ims/oneroster/rostering/v1p2/courses/course-example',
      name: 'Fractions',
    },
    activity: { name: 'Adding fractions' },
    process: true,
  },
  metrics: [
    { type: 'totalQuestions', value: 5 },
    { type: 'correctQuestions', value: 4 },
    { type: 'xpEarned', value: 10 },
    { type: 'masteredUnits', value: 0 },
  ],
})

if (result.jobId && result.jobId !== '0') {
  const job = await client.jobs.waitForCompletion(result.jobId)
  console.log(job.state, job.returnValue)
}

import os
from timeback_caliper import CaliperClient, ActivityCompletedInput

client = CaliperClient(
    platform="BEYOND_AI",
    env="staging",
    client_id=os.environ["CALIPER_CLIENT_ID"],
    client_secret=os.environ["CALIPER_CLIENT_SECRET"],
)

# Run this code inside your async application.
result = await client.events.send_activity(
    "https://learning.example.com",
    ActivityCompletedInput(
        id="urn:uuid:437620ad-f9c9-4a9d-9232-37676bfcf28e",
        event_time="2026-09-11T15:00:00.000Z",
        actor={
            "id": "https://api.example.com/ims/oneroster/rostering/v1p2/users/student-example",
            "type": "TimebackUser",
            "email": "learner@example.com",
        },
        object={
            "id": "https://learning.example.com/activities/fractions",
            "type": "TimebackActivityContext",
            "subject": "Math",
            "app": {"name": "Example Learning App"},
            "course": {
                "id": "https://api.example.com/ims/oneroster/rostering/v1p2/courses/course-example",
                "name": "Fractions",
            },
            "activity": {"name": "Adding fractions"},
            "process": True,
        },
        metrics=[
            {"type": "totalQuestions", "value": 5},
            {"type": "correctQuestions", "value": 4},
            {"type": "xpEarned", "value": 10},
            {"type": "masteredUnits", "value": 0},
        ],
    ),
)

if result.job_id and result.job_id != "0":
    job = await client.jobs.wait_for_completion(result.job_id)
    print(job.state, job.return_value)

The numeric XP value is supplied by the producer. It is not calculated from elapsed time. See Timeback activity and time events for metric fields and SDK events for SDK-specific construction.

Build once, retry the same event

sendActivity and sendTimeSpent create a fresh event ID and timestamp when you omit them. Calling a convenience method again without preserving those fields can create a distinct event. For durable delivery, build the event once using createActivityEvent or createTimeSpentEvent, retain the event payload, and send it with client.events.send(sensor, events). The Python factories are create_activity_event and create_time_spent_event. Preserve the original event and metric collection identities across transport retries. Do not edit a submitted payload and reuse its event ID as a replacement operation. The legacy event store retains the first content for an external ID. Use your integration’s correction procedure.

Methods

Operation	TypeScript	Python
Send event array	`events.send(sensor, events)`	`events.send(sensor_id, events)`
Send envelope	`events.sendEnvelope(envelope)`	`events.send_envelope(envelope)`
Activity helper	`events.sendActivity(sensor, input)`	`events.send_activity(sensor_id, input)`
Time helper	`events.sendTimeSpent(sensor, input)`	`events.send_time_spent(sensor_id, input)`
Validate without storage	`events.validate(envelope)`	`events.validate(envelope)`
List stored events	`events.list(params)`	`events.list(...)`
Get external event ID	`events.get(externalId)`	`events.get(external_id)`
Iterate results	`events.stream(params)`	`events.stream(...)`
Inspect a job	`jobs.getStatus(jobId)`	`jobs.get_status(job_id)`
Poll a job	`jobs.waitForCompletion(jobId)`	`jobs.wait_for_completion(job_id)`

Validation, queries, and polling require a configured path for that operation. The send result’s jobId/job_id can be absent. The batch API’s compatibility value "0" is not a job to poll.

Job monitoring

For a legacy job, polling stops when queue state is completed, and raises for failed or timeout. It does not inspect every semantic error in the worker result. Inspect returnValue in TypeScript or return_value in Python, including any error or partial-result information. A completed queue job does not prove that all webhook subscribers or downstream analytics succeeded. Verify the expected persisted result separately.

Historical queries

Legacy event listing supports limit, offset, sensor, actor ID, actor email, start date, and end date. For example:

const { events } = await client.events.list({
  limit: 20,
  sensor: 'https://learning.example.com',
  startDate: '2026-09-11T00:00:00.000Z',
})

result = await client.events.list(
    limit=20,
    sensor="https://learning.example.com",
    start_date="2026-09-11T00:00:00.000Z",
)
events = result.events

The legacy query store is not a complete search of events sent through other ingestion systems. Check the event destination before treating an empty query as a missing send.

Generic and question events

events.send accepts event objects, but the server still enforces its selected schema. Support for an event in one platform does not guarantee support in another, and schema acceptance does not itself award XP. The client also provides question-seen, question-answered, and question-graded factories. Their destination-specific shapes should be checked against the assigned contract before use. Use the Partner Event Reference or Platform Event Reference for those APIs.

Error handling

The current package does not export an ApiError class. Handle failures using the errors provided by your installed client version. A portable error boundary can inspect error instanceof Error for a message; avoid logging access tokens or raw student event payloads. Correct validation and authorization failures before retrying. For ambiguous network or server failures, retain event identity and use bounded retries. Confirm the resulting activity through the destination’s supported read APIs.

Getting Started

CLI

SDK

Reference

​Platform capabilities

​Installation

​Send an activity

​Build once, retry the same event

​Methods

​Job monitoring

​Historical queries

​Generic and question events

​Error handling