Workout Data

Workout Data

Standard workout commands are affected by --local-time, which converts UTC timestamps in JSON output to the local timezone. Concept2 Rowing and Ski responses already return the record's local workoutDate together with its IANA timezone; do not reinterpret that field with --local-time. --start / --end input params remain UTC.

Authentication

voltra workout auth-check
voltra workout auth-check --api-key <API_KEY>

Querying Workouts

voltra --json workout list --page 1 --page-size 5
voltra --json workout list --start 2026-06-01 --end 2026-06-23
voltra --json workout list --workout-type 1
voltra --json workout sets 211167
voltra --json workout reps 211167 <SET_ID>

Common output fields: id, workoutTypeName, startTime / endTime, setCount / repCount, actionIds / actionNames.

Isometric Test Results (workout type 5)

The standard workout list supports --workout-type 5 for historical Isometric tests. The list response is unchanged; maxPullForceLbs is the test's peak-force summary in lbs. Fetch the workout's sets to receive the optional isometricResult object on each set:

voltra --json workout list --workout-type 5 --page-size 50
voltra --json workout sets <WORKOUT_ID>

{
  "id": 1340811,
  "position": 1,
  "deviceIdentity": "master",
  "repCount": 1,
  "durationSec": 3,
  "maxPullForceLbs": 23.1,
  "isometricResult": {
    "peakForceN": 102.754,
    "rfdNPerSec": 88.97,
    "timeToPeakForceMs": 1010,
    "impulseNSec": 2.313,
    "testTimeMs": 2870,
    "forceDataRateHz": 100
  }
}

The nested Isometric force values use N/N·s, unlike standard *Lbs fields. Convert explicitly when comparing them: 1 lbf = 4.4482216152605 N. testTimeMs and timeToPeakForceMs are elapsed durations, not timestamps, and --local-time does not change them. Older records may omit isometricResult or individual subfields; missing values are not replaced with zero. The reps endpoint does not return the raw force curve, and realtime Isometric result streaming is outside this history API. The force trace has pre/run/post segments: testTimeMs is the run segment, timeToPeakForceMs starts at the run segment, and RFD uses the first 10 run samples. impulseNSec should be treated as the returned device/service metric; its exact integration window is not reproducible from this API because the raw curve is not returned.

Concept2 Rowing and Ski (read-only)

These commands read Concept2 Logbook records belonging to the current VOLTRA API Key. Select the command that matches the Concept2 activity. C2 records are read-only; creation, modification, and deletion are temporarily unsupported.

Use a sport-specific public command for each Concept2 activity: c2-rowing for Concept2 Rowing and c2-ski for Concept2 Ski. Both commands are read-only; there is no unfiltered public command that mixes the two sports.

voltra --json workout c2-rowing list --page 1 --page-size 50
voltra --json workout c2-ski list --page 1 --page-size 50
voltra --json workout c2-rowing detail 1189
voltra --json workout c2-ski detail 1189
voltra --json workout c2-ski monthly --timezone Asia/Shanghai --months 2026-03,2026-02

C2 list/detail summary fields include id, workoutDate, timezone, workoutType, completed, distanceM, durationSec, avgPaceDsPer500m, strokeRatePerMin, strokeCount, dragFactor, and totalCaloriesKcal when available. C2 fields use the Concept2 units: distanceM is meters; durationSec and timeSec are seconds with 0.1-second precision; avgPaceDsPer500m and paceDsPer500m are integer deciseconds (ds, 0.1 seconds) per 500 m, not mm:ss strings. Divide by 10 for seconds: 1755 means 175.5 s/500 m, or 2:55.5/500 m in clock-style display. strokeRatePerMin is strokes per minute; and totalCaloriesKcal is kcal. heartRateBpm is omitted when unavailable or when the source value is 255. workoutDate is local record time, and timezone identifies that local time. The strokeData values are cumulative to each stroke, not deltas from the previous stroke.

The CLI output uses ergType: "rowerg" for Concept2 RowErg and ergType: "skierg" for Concept2 SkiErg.

Monthly grouping converts each record's UTC ingestion time to the requested timezone before assigning its yyyy-MM month. Monthly fields are month, workoutCount, totalDistanceM, totalDurationSec, totalStrokeCount, and totalCaloriesKcal. workoutDate is local to the record's returned IANA timezone; it is not rewritten by --local-time.

Deleting Your Beyond Workout Records

This command permanently deletes the current user's Beyond app workout records and their set data. It only operates on BP application records. The backend silently ignores foreign, missing, already-deleted, and re-submitted IDs and returns data: null without per-ID results. The CLI requires --yes, so confirm the exact Beyond records with the user before running it.

voltra --json workout records delete 167495 167496 --yes

The CLI prints the API's null data payload on stdout when --json is used and emits a warning on stderr. null means the request returned successfully; it does not confirm which IDs were deleted. Deletion of matching Beyond records is physical and cannot be undone.

API Responses and Errors

With --json, successful commands print the API data payload. Business errors retain the backend code and message even though the HTTP response is 200: 10203 means a required parameter is missing, 10206 an invalid parameter, 10207 rate limiting, 10801 a missing or unauthorized workout, and 40300 that the feature is not enabled. Missing or invalid AI Access Tokens use HTTP 401 with codes 40800 and 40801 respectively.

Aggregation

voltra --json workout aggregate-sets --start 2026-06-01 --end 2026-06-23
voltra --json workout aggregate-sets --start 2026-06-01 --end 2026-06-23 --workout-type 1 --action-id 33
voltra --json workout aggregate-reps --start 2026-06-01 --end 2026-06-23 --group-by day

Script Examples

# Last 5 workout summaries (local timezone)
voltra --local-time --json workout list --page 1 --page-size 5 \
  | jq -r '.list[] | "\(.id)\t\(.workoutTypeName)\t\(.startTime)\tsets=\(.setCount)\treps=\(.repCount)"'

# Drill down into a specific workout
WORKOUT_ID=$(voltra --json workout list --page 1 --page-size 1 | jq -r '.list[0].id')
voltra --json workout sets "$WORKOUT_ID"

SET_ID=$(voltra --json workout sets "$WORKOUT_ID" | jq -r '.list[0].id')
voltra --json workout reps "$WORKOUT_ID" "$SET_ID"