Trainings

A training is a completed workout associated with an Uptivo user. Every Training operation returns the same flat ClubTrainingDTO. Optional query flags can add the current Athlete representation, raw telemetry, or both.

Choose an operation

Need	API reference
Synchronize all accessible trainings	GET /Trainings
Synchronize one athlete’s trainings	GET /Athletes/{userId}/Trainings
Read one training	GET /Trainings/{trainingId}

The flags are independent:

• withTelemetry=true adds the Telemetry property with the five raw sample series;
• withUser=true adds User as a ClubAthleteDTO when the owner is still an Athlete of the selected club.

Both flags default to false. Use the base response for synchronization when aggregate fields such as duration, heart rate, points, calories, distance, power, and cadence are sufficient. Telemetry payloads are substantially larger and use lower page limits.

Training origin

The optional origin filter accepts Any, Club, or Personal. If omitted, the enum default is Any.

For the global GET /Trainings operation:

origin	Returned trainings
Club	Trainings whose ClubId is the club selected by the Club API Key.
Personal	Trainings belonging to current athletes whose ClubId is either null or different from the club selected by the Club API Key.
Any	The selected club’s trainings plus all trainings belonging to users who are currently athletes of the club.

For GET /Athletes/{userId}/Trainings, the athlete must currently belong to the selected club. Once that check succeeds, Club means ClubId equals the selected club, while Personal means the training was performed outside that club. A personal training can therefore have ClubId: null or identify a different club. Any returns both.

Synchronize trainings by ID

Start a forward synchronization with fromId=1:

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/Trainings?origin=Any&fromId=1&count=100" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

Without telemetry, the global and per-athlete operations default to 30 results and allow at most 100. Repeat the selection and range parameters from the first request and pass each opaque continuation unchanged:

GET /Trainings?origin=Any&fromId=1&count=100
GET /Trainings?origin=Any&fromId=1&count=100&cursor=<NextCursor>

NextCursor always moves to larger TrainingId values and PrevCursor to smaller ones, independently of the first page’s result order. Persist a cursor only after the entire page has been processed durably. Store the endpoint and selection parameters with the cursor so the traversal can be reconstructed. The withTelemetry and withUser enrichment flags do not alter the selected rows or cursor position and may be changed between continuation requests. See Pagination and synchronization for the complete loop, latest-N import, retry, reconciliation, and webhook guidance.

An ID checkpoint discovers newly created trainings. It does not discover an update or deletion of an older ID, so combine it with training webhooks and a periodic reconciliation scan.

Use a time range when needed

Training lists also accept an inclusive from/to range over the training’s Begin timestamp:

GET /Trainings?origin=Club&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&count=100

Repeat all parameters from the first request and pass the opaque token:

GET /Trainings?origin=Club&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&count=100&cursor=<NextCursor>

The cursor preserves exact (Begin, TrainingId) ordering, so equal timestamps are not lost. A from-only traversal can later poll towards newer Begin values. A fixed to remains part of the filter and prevents that cursor from reading beyond it. Begin is activity time rather than creation or update time, so backdated uploads and corrections still require overlapping reads, webhooks, and reconciliation.

Choose response enrichments

List request	Response item	Default count	Maximum count
withTelemetry=false	Flat ClubTrainingDTO	30	100
withTelemetry=true	Flat ClubTrainingDTO with Telemetry	10	30

withUser does not change the page-size limits. All three operations return the same flat ClubTrainingDTO, with training fields and optional enrichments at the top level. Important identity fields are TrainingId, UserId, and ClubId. Use TrainingId to retrieve or reconcile a training. Interpret ClubId relative to the club selected by the Club API Key: equality means Club; a different value or null means Personal.

Begin and End are ISO 8601 timestamps. BeginDateLocal is the stored calendar date of the start in the athlete’s timezone, formatted YYYY-MM-DD. Use it when grouping workouts by the athlete’s local day; do not derive it from the UTC date alone. Duration and zone-time fields use the .NET duration format days.hours:minutes:seconds.fraction.

Use Making requests for canonical units and the GET /Trainings reference for the complete ClubTrainingDTO schema.

When withTelemetry=true, Telemetry contains HeartBeats, GeoPositions, Powers, Cadences, and Hits. Empty arrays mean that no qualifying samples were found. When telemetry was not requested, the complete Telemetry property is omitted.

When withUser=true, User contains the current ClubAthleteDTO. The property is omitted when user enrichment was not requested and also for a historical club training whose owner is no longer an Athlete of the selected club.

For example, request both enrichments without changing the selected rows:

GET /Trainings?origin=Any&fromId=1&count=30&withTelemetry=true&withUser=true

Read one training

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/Trainings/400001?withTelemetry=true&withUser=true" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The detail operation returns a training when it was performed in the selected club or when its owner is currently an athlete of that club. This keeps club history readable after an athlete leaves while still allowing the club to read that current athlete’s workouts performed elsewhere. It returns 404 Not Found when neither condition is true.

Errors and permissions

All operations require Read or ReadWrite access. A missing or invalid credential returns 401; an inactive Club API license or insufficient key permission returns 403.

Training lists return 400 for inverted ranges, equal date boundaries, a request that combines ID and date filters, an explicit count=0, or a count that cannot be parsed as an unsigned integer. A positive count above the applicable maximum is accepted and reduced to 100, or to 30 when withTelemetry=true. Athlete-specific lists return 404 when the athlete is absent or outside the selected club. See Errors for the common handling strategy and continue with Telemetry when raw samples are required.