Workout Events
Events for the workout lifecycle and statistics: workouts, plan workouts, personalized plans, custom workouts, challenges, AI Trainer workouts and the Gym Log.
| Event | Data Fields | Description |
| workout_opened | id: string, title: string, date: string | A workout's detail page loaded (Workout and Plan integrations, workouts opened from Home). Once per opened workout. Not sent for custom workouts, challenges or AI Trainer workouts |
| workout_started | id: string, date: string | A new run started on the exercise screen, including a restart. In the Gym Log it is sent each time the log screen opens |
| workout_resumed | id: string, date: string | The workout screen opened again during the same run (for example after Android back from the exercise screen). Sent instead of a second workout_started, so do not count it as a new attempt. A challenge that has started never resumes: going back into it starts a new run with its own workout_started |
| workout_started (legacy home) | workoutId: string | The "Start workout" button of the legacy KinesteX home. The exercise screen then sends its own workout_started |
| workout_progress | data: object | Live progress, sent after every completed exercise and on request (see below) |
| workout_ended | id: string, exit_type: string, date: string | Workout session ended (see exit_type values below) |
| workout_overview | data: object | Workout summary, sent when the results screen opens. Sent again when a past session is opened from the AI Trainer's progress. Not sent by the personalized-plan assessment, which ends on its own results |
| workout_restart | data: { workout: string, date: string } | User tapped Restart on the results screen. No workout_completed or exit event follows; a new workout_started comes when the run starts again. A custom workout assessment sends it too |
| workout_completed | data: { workout: string, date: string } | The user left the results screen (Continue or close). workout is the workout title. Always followed by exactly one routing event, see Navigation Events |
| statistic_sheet_opened | - | The motion replay sheet opened on the results screen |
| statistic_subpage_opened | - | The detailed per-exercise breakdown opened on the results screen |
| statistic_subpage_closed | - | The detailed breakdown closed |
On the results screen the events come in this order: workout_overview, challenge_completed (challenges and runs started from Home), exercise_overview, custom_assessment_completed (custom workout assessments), then the session save events when saving is on.
Custom Workout loading:
| Event | Data Fields | Description |
| custom_workout_ready | message: string ("Ready to receive workout data") | The Custom Workout page is up and waiting for your workout data |
| commit_screen_shown | data: { commit_button: boolean } | Verification finished and the loading screen shows its own progress, so you can drop your loading cover. commit_button is true with showCommitScreen. Sent again if it changes |
| all_resources_loaded | message: string ("Custom workout data loaded successfully") | Videos, rest speech, motion models and pose tracking are loaded. Custom Workout and AI Trainer workouts. Not sent while a failed load waits for Retry. On a Custom Workout, send { workout_activity_action: "start" } now (with showCommitScreen, after workout_committed) |
| workout_committed | data: { orientation_permission: string } | Custom Workout with showCommitScreen only: the user tapped "I'm committed". orientation_permission is "granted", "denied", "unsupported" or "error". Send start after it |
Command echoes. When you send a workout_activity_action, the workout confirms it with an event of the same type, carrying date ("DD MM YYYY HH:MM:SS"):
| Event | When |
| pause_workout / resume_workout | Only when the state changed: pausing a paused workout sends nothing. A pause the user taps on screen sends nothing either |
| mute_workout / unmute_workout | Every time. The Camera component echoes these too |
| mute_speech / unmute_speech | Every time. Workouts and Gym Log only: the Camera component ignores them |
log replies with workout_progress (below).
Gym Log (motion tracking off): in workouts, plans, custom workouts and the AI Trainer, users log their sets in the Gym Log when AI motion tracking is off (unless you pass selfModeEnabled: false). It sends the same workout_started, exercise_completed, workout_progress and workout_ended events with the same shapes, echoes the commands above, and ends on the same results events. The differences: workout_started is sent each time the log screen opens; exercise_completed is sent for every set closed (logged or skipped), again after a redo, and again with the corrected numbers when the user edits a set, so treat it as an update; its mistakes is always []; workout_progress follows each batch of corrections; workout_ended is only complete or exit. There are no camera or motion events. See Motion Tracking Settings.
workout_progress Data Structure:
1{
2 completion_percentage: number, // 0-100, same formula as workout_overview
3 completed_reps_count: number,
4 target_reps_count: number,
5 calories_burned: number, // 2 decimal places
6 exercise_index: number, // 1-based, rest periods not counted
7 total_exercises: number, // rest periods not counted
8 workout_id?: string, // omitted when unknown
9 workout_title?: string, // omitted when unknown
10 date: string // "DD MM YYYY HH:MM:SS", device-local
11}To get fresh numbers at any moment (for example, right before your app goes to the background), send { workout_activity_action: "log" }. The SDK replies with a new workout_progress, or with error_occurred (severity: "warning", message: "log: no active workout") when no workout is loaded. A workout counts as loaded from its detail page until the user leaves the results screen.
workout_ended exit_type values:
| Value | Meaning |
| complete | User finished the entire workout including outro (in the Gym Log: every set was logged or skipped) |
| exit | User abandoned the workout mid-session |
| outro | User exited from the outro/cooldown screen after completing all exercises. Not sent by the Gym Log |
workout_overview Data Structure:
1{
2 workout_title: string, // Workout name (omitted when unknown)
3 workout_id: string, // Unique workout ID (omitted when unknown)
4 target_duration_seconds: number, // Target workout duration (seconds)
5 workout_duration_seconds: number, // Total wall-clock session time
6 // (includes rest, transitions, pauses).
7 // For challenges/assessments this equals
8 // total_time_spent (no wall-clock concept)
9 total_time_spent: number, // Active exercise time only (seconds)
10 completed_reps_count: number, // Total completed reps
11 target_reps_count: number, // Total target reps
12 calories_burned: number, // Calories (2 decimal places)
13 completion_percentage: number, // Completion % (2 decimals)
14 total_mistakes: number, // Total mistake count
15 accuracy_score: number, // Overall accuracy (0-100)
16 efficiency_score: number, // Efficiency metric (0-100)
17 total_exercise: number, // Number of exercises (rest periods not counted)
18 actual_hold_time_seconds: number, // Time in correct position
19 target_hold_time_seconds: number // Target hold time
20}Note: Use workout_duration_seconds to display or log the full session time (including rest periods). Use total_time_spent if you only need active exercise time.
The same data also carries older names of these values: workout (the workout id or null), total_repeats, total_calories, percentage_completed, total_max_reps, total_accuracy_score and total_max_time. Prefer the names above. The Camera component sends a workout_overview with different fields, see Camera & Frame Events.
1case .workout_overview(let json):
2 // The summary is under "data"; json is the whole event
3 if let overview = json["data"] as? [String: Any],
4 let calories = overview["calories_burned"] as? Double,
5 let completion = overview["completion_percentage"] as? Double {
6 print("Burned \(calories) cal, \(completion)% complete")
7 }