Workout History Upload

How Cortex saves completed VOLTRA workouts locally, uploads them automatically, and recovers from offline or failed uploads.

Workout History Upload

Cortex handles workout history in two stages:

The connected daemon captures a completed workout and saves a durable local artifact.
An uploader sends due artifacts to Beyond History.

The artifact is saved before the network request. If the network is unavailable, the API key is missing, or the server asks for a retry, the workout stays in the local queue instead of being discarded.

This page covers uploading history created by a connected VOLTRA device. For querying workouts that are already in Beyond History, see Workout Data.

Before you start

Configure the VOLTRA API key once. Upload commands read it from the local Cortex configuration; do not paste a key into normal upload commands.

voltra config set-api-key "<VOLTRA_API_KEY>"
voltra workout auth-check --json

voltra workout upload does not import arbitrary JSON files and does not accept a per-command --api-key flag. It only processes artifacts created by the connected daemon.

Automatic upload

After voltra connect <DEVICE_ID>, the daemon captures completed workouts in the background. The automatic scope currently includes:

Weight Training
Resistance Band
Damper
Isokinetic
Isometric
Custom Curve
Rowing
Skiing

Sled Pull is not included in automatic History capture.

When the daemon has a configured API key and the network is available, due queue jobs are uploaded automatically. When the network comes back, the daemon resumes due jobs. If the daemon is not running, start an upload manually after reconnecting:

voltra workout upload --json

voltra stream is a live telemetry command. It does not upload workout history and is not required for the History uploader to work.

Inspect and upload the queue

Use upload-status to inspect the local queue. It does not contact the API.

# Pending, retrying, blocked, and unresolved jobs
voltra workout upload-status --json

# Include jobs that already have a remote workout ID
voltra workout upload-status --include-succeeded --json

An empty jobs array means there are no visible local jobs waiting for upload or reconciliation. It does not mean that the remote workout history is empty. Use voltra workout list to query remote history.

Process due jobs manually with:

voltra workout upload --json

The default maximum is 20 jobs per run. Increase or reduce it when needed:

voltra workout upload --max-jobs 5 --json

The JSON result contains an uploaded summary:

Field	Meaning
`attempted`	Jobs processed in this invocation.
`succeeded`	Jobs confirmed with a remote workout ID.
`retryWait`	Jobs that should be retried later, usually after a temporary network or server error.
`blocked`	Jobs that need investigation before they can be retried automatically.
`results`	Per-job status, error, retry time, and remote workout ID when available.

Job statuses

upload-status --json reports these local statuses:

Status	Meaning	What to do
`ready`	Waiting to be processed.	Run `voltra workout upload`.
`uploading`	Currently leased by an uploader.	Wait for the current run to finish.
`retry_wait`	A temporary failure is scheduled for retry.	Wait for the retry time or run the command again later.
`blocked`	The error is not safe to retry automatically.	Read `lastError`, fix the cause, then use `upload-retry`.
`succeeded`	The server returned a remote workout ID.	No action is needed. Hidden by default in queue status.

If a request may have reached the server but the response did not contain remoteWorkoutId, Cortex reconciles the remote History before posting the same workout again. Do not manually upload the same workout a second time while it is waiting for reconciliation.

Retry a blocked job

First inspect the job ID and lastError:

voltra workout upload-status --json

After fixing the cause, reset one job or all non-succeeded jobs and process them:

voltra workout upload-retry --job-id <JOB_ID> --json
voltra workout upload-retry --all --json

Use --job-id for a targeted retry. Use --all only when the same temporary problem affected the whole queue. Both options reset the selected jobs to ready before processing them.

Local queue and recovery

The default queue directory is:

~/.voltra/history-upload/

It contains the durable queue and its lock/backups, including queue.json and queue.json.bak.*. The queue is local to the current user and is not the remote workout history database.

Do not edit or replace queue.json while Cortex is running. If the file contains invalid JSON, upload-status reports an error and preserves the original queue instead of clearing it. Keep the original file and its backups for recovery or support diagnosis.

Common checks

# Confirm the configured credential
voltra workout auth-check --json

# See what is waiting locally
voltra workout upload-status --json

# Process due jobs
voltra workout upload --json

# Verify successful jobs and their remote IDs
voltra workout upload-status --include-succeeded --json

# Query the server after upload/reconciliation
voltra workout list --page 1 --page-size 10 --json

If a job remains blocked, keep its job ID and lastError when reporting the problem. Do not include the API key or the full workout payload in a support request.

Workout History Upload

On this page