modelhealth

Initializes the client.

Arguments:

• api_key: Your Model Health API key, available in the dashboard at modelhealth.io.
• timeout: Per-request timeout in seconds for JSON API calls. Bulk transfers (archive downloads, video uploads) are not bounded by it. If omitted, the build's default is used.
• max_retries: Number of retries on transient network or request failures. If omitted, the build's default is used.

Raises:

• AuthenticationError: If the API key is not valid.

Example:

from modelhealth import ModelHealthClient

client = ModelHealthClient("your_api_key")

# List sessions and subjects
sessions = client.session_list()
subjects = client.subjects.list().all()

Verifies the API key and returns information about the authenticated account.

A cheap way to check that the API key is valid without performing a domain operation.

Returns:

An AccountInfo with the authenticated account's identity and licensing details.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.

Example:

info = client.account_info()
print(f"Authenticated as {info.email}")

Returns the current billing/quota state for the authenticated account.

Use this to show usage bars and plan limits, and to block recording in your own UI when the quota is exhausted or the subscription has lapsed.

reason explains why recording_allowed is False, and is only set in that case. Most other detail fields (reason, activities_used, activities_max, period_end, plan_name, reset_period) are None when there is no active plan. An activities_max of None while a plan is active means the plan is unlimited.

Returns:

A UsageInfo describing the account's current billing and quota state.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.

Example:

usage = client.usage()
if not usage.recording_allowed:
    print(f"Recording blocked: {usage.reason}")

Retrieves all sessions for the account associated with the API key.

Use this to list existing sessions before creating a new one, or to resume a previous capture workflow.

To connect a device to a specific session, use the session qrcode URL to download the QR code image data, then display it in your app to be captured by the ModelHealth mobile app.

Returns:

A list of Session objects, or an empty list if none exist.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

import urllib.request

sessions = client.session_list()
print(f"Found {len(sessions)} sessions")

if sessions:
    first = sessions[0]
    with urllib.request.urlopen(first.qrcode) as resp:
        qr_image_data = resp.read()
    # Display qr_image_data in your app so the mobile app can scan it

Retrieve a specific session by ID with all activities populated.

Arguments:

• session_id: The id of the session to retrieve.

Returns:

A Session with activities populated.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the session does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

session = client.get_session("abc123")
for activity in session.activities:
    print(f"{activity.name or activity.id}")

Points the cameras at the session to record subject in.

Use this to move between subjects in any order, including going back to someone recorded earlier. The session already recording that subject is reused when its camera calibration and static pose are both still good, so the pose does not have to be repeated. Otherwise a new session is started from session, exactly as new_session_from_session() would.

Arguments:

• subject: The subject to record next.
• session: The session the cameras are pointed at now.

Returns:

The Session to record in. May be one that already existed, the one passed in, or a new one.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the session or subject does not exist.
• UnsupportedOperationError: If the API version in use cannot hand the cameras back to an existing session.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

# Everyone does exercise 1, then everyone does exercise 2
for exercise in ("CMJ", "Squat"):
    for subject in subjects:
        session = client.switch_subject(subject, session)
        activity = client.start_recording(exercise, session)
        client.stop_recording(session)

Creates a new session from a previous session, inheriting its calibration setup.

Use this to move directly to calibrating a new subject without repeating camera connection or checkerboard calibration.

Arguments:

• session: The previous, already-calibrated session.

Returns:

A new Session ready for a new subject.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the session does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

new_session = client.new_session_from_session(previous_session)

Creates a session.

A session is the parent container for a movement capture workflow. It links related entities such as activities and subjects and provides the context used by subsequent operations.

Default session settings are applied automatically. Call configure_session() afterwards to override specific settings.

Returns:

A new Session with a unique identifier.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

session = client.create_session()

Applies settings to an existing session.

Call this after create_session() and before calibration to override any default settings. If not called, the session retains the defaults applied during creation.

All parameters are optional — omit any to keep its default.

Arguments:

• session: The session to configure.
• framerate: Camera frame rate. Default: SessionFramerate.fps_120.
• opensim_model: OpenSim model. Default: SessionOpenSimModel.lai_uhlrich_2022.
• scaling_setup: Scaling pose. Default: SessionScalingSetup.upright_standing_pose.
• core_engine: Core engine version. Default: SessionCoreEngine.v1_0.
• filter_frequency: Low-pass filter frequency. Default: FilterFrequencyDefault().
• data_sharing: Data-sharing preference. Default: SessionDataSharing.share_processed_data_and_identified_videos.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

session = client.create_session()
client.configure_session(
    session,
    framerate=SessionFramerate.fps_60,
    data_sharing=SessionDataSharing.share_no_data,
)

Retrieves a subject by its ID.

Use this to resolve a subject ID (e.g. from Session.subject) into full subject details without fetching the entire subject list.

Arguments:

• subject_id: The unique identifier of the subject.

Returns:

The Subject with its current details.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the subject does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

subject = client.fetch_subject(session.subject)
print(f"Subject: {subject.name}")

Creates a subject profile.

Height and weight are required for biomechanical analysis. Once created, the subject can be calibrated using calibrate_subject().

Arguments:

• parameters: The subject's profile details including name and anthropometrics.

Returns:

The newly created Subject with its assigned ID.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On validation failure, request failure or an unexpected response.

Example:

from modelhealth import SubjectParameters

params = SubjectParameters(
    name="John Smith",
    weight=75.0,
    height=180.0,
    birth_year=1990,
)
subject = client.create_subject(params)
print(f"Created subject with ID: {subject.id}")

# Use the subject for calibration
client.calibrate_subject(subject, session, lambda s: print(s))

Retrieves an activity by its ID.

Use this to fetch the latest state of an activity, including its videos, results and current processing status.

Arguments:

• activity_id: The unique identifier of the activity.

Returns:

The Activity with its current details.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the activity does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

activity = client.fetch_activity("abc123")
print(f"Activity: {activity.name or 'Unnamed'}")
print(f"Status: {activity.status}")

Updates an activity.

Only mutable fields (such as name) are applied. Use the returned object rather than the input going forward.

Arguments:

• activity: The Activity to update, with modified properties.
• config: Optional config to apply alongside the update. Supports add_tags/remove_tags to modify tags and name to rename.

Returns:

The updated Activity as stored.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the activity does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Deletes an activity.

Permanently removes the activity and all associated videos, results, and metadata.

Arguments:

• activity: The Activity to delete.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If the activity does not exist.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

client.delete_activity(activity)

Warning:

This operation is irreversible.

Retrieves all available activity tags.

Use the returned tags to populate a tag picker or validate tag values before assigning them to activities.

Returns:

A list of ActivityTag objects, or an empty list if none are configured.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

tags = client.activity_tags()
for tag in tags:
    print(f"{tag.label}: {tag.value}")

Retrieves all movement activities associated with a session.

Activities represent individual recording trials and contain references to captured videos and results. Use this to review past data or fetch results for completed activities.

Arguments:

• session: The session whose activities to retrieve.

Returns:

A list of Activity objects, or an empty list if none exist.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

activities = client.activity_list(session)
for activity in activities:
    print(f"{activity.name or activity.id}")
    print(f"  Videos: {len(activity.videos)}")
    print(f"  Results: {len(activity.results)}")

Uploads external files (e.g. sensor data) to an activity.

Posts each file as a separate result entry and returns a refreshed activity reflecting the new results. All files are uploaded in parallel.

Arguments:

• activity: The Activity to attach external files to. Must have completed processing (ActivityStatus.ready).
• files: One or more ExternalResultFile instances, with tag, file extension and data.

Returns:

A refreshed Activity containing the new result entries.

Raises:

• ModelHealthError: If any tag is reserved, empty or duplicated, or if any file exceeds the 100 MB size limit.
• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

from modelhealth import ExternalResultFile

with open("sensor_data.csv", "rb") as f:
    csv_data = f.read()

file = ExternalResultFile("acme-sensor", "csv", csv_data)
activity = client.add_motion_data_to_activity(activity, [file])

Downloads video data for a specific activity.

Fetches all videos associated with the activity that match the specified version. Videos with invalid URLs or failed downloads are silently excluded from the result.

Arguments:

• activity: The Activity whose videos to download.
• version: VideoVersion.raw for original per-camera recordings, or VideoVersion.synced for temporally-synchronised output.

Returns:

A list of raw video bytes (one per camera). Write each element to a .mp4 file for playback. May be empty if no videos are available or all downloads fail.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

videos = client.videos_for_activity(activity, VideoVersion.synced)
for i, video in enumerate(videos):
    with open(f"video_{i}.mp4", "wb") as f:
        f.write(video)

Downloads motion data from a processed activity.

Use this after an activity reaches ActivityStatus.ready to retrieve biomechanical result files such as kinematics, marker data, or an OpenSim model. Failed downloads are silently excluded from results.

Arguments:

• activity: The Activity whose results to download. Must have completed processing.
• data_types: Motion data types to fetch. Valid values: "animation", "kinematics_mot", "kinematics_csv", "markers_trc", "markers_csv", "model".

Returns:

A list of MotionData objects, one per successfully downloaded type. May be empty if no results are available or all downloads fail.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

results = client.motion_data_for_activity(
    activity, [MotionDataType.kinematics_mot, MotionDataType.animation]
)
for r in results:
    if r.type == "kinematics_mot":
        with open("kinematics.mot", "wb") as f:
            f.write(r.data)  # MOT format
    elif r.type == "animation":
        import json
        transforms = json.loads(r.data)  # JSON format
    elif r.type == "markers_trc":
        with open("markers.trc", "wb") as f:
            f.write(r.data)  # TRC format
    elif r.type == "model":
        with open("model.osim", "wb") as f:
            f.write(r.data)  # OSim format

Downloads result data for an activity with a completed analysis.

Call this after analysis_status() returns AnalysisStatus.completed to retrieve metrics, a report, or raw data. Failed downloads are silently excluded from results.

Arguments:

• activity: The Activity whose analysis results to download. Must have a completed analysis.
• data_types: Analysis result types to fetch. Valid values: "metrics" (JSON), "report" (PDF), "data" (ZIP).

Returns:

A list of AnalysisData objects, one per successfully downloaded type. May be empty if no results are available or all downloads fail.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

import json

results = client.analysis_data_for_activity(
    activity, [AnalysisDataType.metrics, AnalysisDataType.report, AnalysisDataType.data]
)
for r in results:
    if r.type == "metrics":
        metrics = json.loads(r.data)
    elif r.type == "report":
        with open("report.pdf", "wb") as f:
            f.write(r.data)
    elif r.type == "data":
        with open("data.zip", "wb") as f:
            f.write(r.data)

Retrieves the current processing status of an activity.

Poll this method after recording stops to track upload and processing progress.

Returns ActivityStatusUploading when videos are uploading, ActivityStatusAnalyzing (with the analysis task) when automatic analysis is running, or an ActivityStatus enum value otherwise.

Arguments:

• activity: The Activity to check status for.

Returns:

The current status as ActivityStatusUploading, ActivityStatusAnalyzing, or ActivityStatus.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

status = client.activity_status(activity)
if isinstance(status, ActivityStatusUploading):
    print(f"Uploading: {status.uploaded}/{status.total}")
elif status == ActivityStatus.processing:
    print("Still processing...")
elif isinstance(status, ActivityStatusAnalyzing):
    analysis_status = client.analysis_status(status.task)
elif status == ActivityStatus.ready:
    print("Activity ready for analysis")
elif status == ActivityStatus.failed:
    print("Processing failed")

Starts an analysis task for an activity that is ready for analysis.

Call this after activity_status() returns ActivityStatus.ready. Use the returned Analysis with analysis_status() to poll progress.

Arguments:

• activity_type: The analysis algorithm to run. Use a ActivityType member.
• activity: The Activity to analyze.
• session: The Session containing the activity.

Returns:

An Analysis for tracking analysis progress.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If the activity is not ready or the request fails.

Example:

task = client.start_analysis(
    ActivityType.counter_movement_jump, activity, session
)
status = client.analysis_status(task)

Retrieves the current status of an analysis task.

Poll this method after start_analysis() to monitor progress. When status reaches AnalysisStatus.completed, download results with analysis_data_for_activity().

Arguments:

• task: The Analysis task returned by start_analysis().

Returns:

The current AnalysisStatus.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

import time

status = client.analysis_status(task)
while status == AnalysisStatus.processing:
    time.sleep(10)
    status = client.analysis_status(task)

if status == AnalysisStatus.completed:
    results = client.analysis_data_for_activity(
        activity, [AnalysisDataType.metrics, AnalysisDataType.report]
    )
elif status == AnalysisStatus.failed:
    print("Analysis failed")

Creates an activity and starts recording a dynamic movement trial.

Must be called after both camera and subject calibration are complete. Call stop_recording() when the subject has finished the movement.

Arguments:

• name: A descriptive name for this activity (e.g. "cmj", "squat").
• session: The session this activity is associated with.
• config: Optional recording configuration.

Returns:

The newly created Activity.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If recording cannot start (e.g. missing calibration).

Example:

activity = client.start_recording("cmj", session, ActivityConfig(ActivityType.counter_movement_jump))
# Subject performs movement...
client.stop_recording(session)

Stops the active recording for a movement trial.

Call this after the subject has completed the movement. Once stopped, the recorded videos begin uploading and can be tracked with activity_status().

Arguments:

• session: The session context to stop recording in.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If there is no active recording or the request fails.

Example:

client.stop_recording(session)

Calibrates cameras using a checkerboard pattern.

Determines each camera's position and orientation in 3D space (extrinsics), enabling reconstruction of real-world movement from multiple 2D video feeds. Required once per session setup — recalibrate only if cameras are moved.

Note:

rows and columns refer to internal corners, not squares. A 5×6 board has 4 internal corner rows and 5 internal corner columns.

This method blocks until calibration completes. The status_callback is called synchronously on each status update during the operation.

Arguments:

• session: The session context in which calibration is performed.
• checkerboard: The checkerboard dimensions and placement.
• status_callback: Callable receiving a CalibrationStatus, CalibrationStatusUploading or CalibrationStatusProcessing on each update.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If calibration fails (e.g. pattern not detected).

Example:

from modelhealth import CheckerboardDetails, CheckerboardPlacement

details = CheckerboardDetails(
    rows=4,       # Internal corners, not squares (for 5×6 board)
    columns=5,    # Internal corners, not squares (for 5×6 board)
    square_size=35,  # Measured in millimeters
    placement=CheckerboardPlacement.perpendicular,
)
client.calibrate_camera(session, details, lambda s: print(s))

Calibrates a subject by recording a neutral standing pose.

Scales the 3D biomechanical model to the subject's body size. Must be run after camera calibration and requires the subject profile to include height and weight.

Important:

The subject must stand upright, feet pointing forward, completely still and fully visible to all cameras for the duration of the recording.

This method blocks until calibration completes. The status_callback is called synchronously on each status update during the operation.

Arguments:

• subject: The subject to calibrate.
• session: The session context in which calibration is performed.
• status_callback: Callable receiving a CalibrationStatus, CalibrationStatusUploading or CalibrationStatusProcessing on each update.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If calibration fails.

Example:

client.calibrate_subject(subject, session, lambda s: print(s))

Starts preparing a session archive for download.

Packaging the session data into a ZIP file starts in the background. Poll archive_status() until status reaches ArchiveStatus.ready, then call archive_data() to download the ZIP file.

Arguments:

• session: The Session to archive.
• with_videos: If True, include raw video files in the archive. Defaults to False.

Returns:

An Archive for tracking preparation progress.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

import time

archive = client.prepare_archive(session)
status = client.archive_status(archive)
while status == ArchiveStatus.processing:
    time.sleep(5)
    status = client.archive_status(archive)

if status == ArchiveStatus.ready:
    data = client.archive_data(archive)
    with open("session.zip", "wb") as f:
        f.write(data)

Retrieves the current preparation status of an archive task.

Poll this method after prepare_archive() to monitor progress. When status reaches ArchiveStatus.ready, download the archive with archive_data().

Arguments:

• archive: The Archive task returned by prepare_archive().

Returns:

The current ArchiveStatus.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

status = client.archive_status(archive)

if status == ArchiveStatus.processing:
    print("Archive being prepared...")
elif status == ArchiveStatus.ready:
    print("Archive ready to download")
elif status == ArchiveStatus.failed:
    print("Archive preparation failed")

Imports a set of activities into Model Health.

Performs the full import workflow: session creation, configuration, subject association, activity creation, video download and upload, processing trigger and polling until complete for each activity.

Arguments:

• activities_json: Raw JSON string of a JSON array of activity objects.
• subject: Subject to associate with the session.
• session_config: Session settings. None uses defaults.
• session_meta_json: Optional JSON string of the source session's meta field. When provided, the new session is patched with this metadata before settings are applied, preserving source data (e.g. sessionWithCalibration) needed for processing.
• status_callback: Optional callable invoked at each step with a status value. Receives one of: "creating_session", ImportStatusCreatedSession, ImportStatusUploading, or "processing".

Returns:

The Session containing all imported activities.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure, invalid JSON or processing failure.

Example:

import json

activities_json = json.dumps([{...}, {...}])  # list of activity dicts

def on_status(status):
    if isinstance(status, ImportStatusUploading):
        print(f"[{status.trial}] Uploading {status.uploaded}/{status.total}")
    else:
        print(status)

session = client.import_session(
    activities_json,
    subject,
    status_callback=on_status,
)

Downloads the prepared session archive as a ZIP file.

Call this after archive_status() returns ArchiveStatus.ready.

Arguments:

• archive: The Archive task returned by prepare_archive().

Returns:

Raw ZIP bytes. Write directly to a .zip file.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If the archive is not ready or the download fails.

Example:

data = client.archive_data(archive)
with open("session.zip", "wb") as f:
    f.write(data)

Returns metric values for a single activity.

Fetches the full set of biomechanical metric values computed for the given activity, grouped by category.

Arguments:

• activity_id: UUID of the activity.

Returns:

An ActivityMetrics instance containing all metric groups and their computed values, or None if the activity has not been analysed yet.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If no activity with activity_id exists.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

metrics = client.activity_metrics("a1b2c3d4-...")
if metrics is None:
    print("No metrics yet — this activity has not been analysed.")
else:
    for group in metrics.groups:
        print(group.name)
        for m in group.metrics:
            print(f"  {m.name}: {m.value}")

Returns metric values for all of a subject's activities.

Fetches metric values across every activity belonging to the subject, optionally filtered to a date range.

Arguments:

• subject_id: Numeric ID of the subject.
• start: Optional ISO date string (YYYY-MM-DD) for the start of the date range (inclusive).
• end: Optional ISO date string (YYYY-MM-DD) for the end of the date range (inclusive).

Returns:

A list of ActivityMetrics instances, one per activity.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NotFoundError: If no subject with subject_id exists.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

all_metrics = client.subject_metrics(42, start="2025-01-01", end="2025-06-30")
for activity_metrics in all_metrics:
    print(activity_metrics.activity_id)

Sets the video upload mode

Arguments:

• mode: The desired video upload mode.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: On request failure or an unexpected response.

Example:

client.set_video_upload_mode(VideoUploadMode.disabled)

Adjusts the log level without touching the registered handler.

Arguments:

• level: How verbose the log event stream should be.

Example:

client.set_log_level(LogLevel.warn)

Registers or clears the persistent log handler.

Passing None for handler clears it regardless of level.

Arguments:

• handler: Called with a LogEvent for each event at or below level. Pass None to stop receiving events.
• level: How verbose the log event stream should be. Ignored when handler is None.

Example:

def handle_log(event: LogEvent) -> None:
    print(f"[modelhealth] {event.code}: {event.message}")

client.set_log_handler(handle_log)

# Stop receiving events
client.set_log_handler(None)

Initializes the client.

Arguments:

• api_key: Your Model Health API key, available in the dashboard at modelhealth.io.
• timeout: Per-request timeout in seconds for JSON API calls. Bulk transfers (archive downloads, video uploads) are not bounded by it. If omitted, the build's default is used.
• max_retries: Number of retries on transient network or request failures. If omitted, the build's default is used.

Raises:

• AuthenticationError: If the API key is not valid.

Example:

from modelhealth import ModelHealthClient

client = ModelHealthClient("your_api_key")

# List sessions and subjects
sessions = client.session_list()
subjects = client.subjects.list().all()

Lazily lists activities matching the given filters.

Arguments:

• subject: Only activities belonging to this subject. Accepts a Subject or its id.
• calibration_session: Only activities recorded under this calibration session. Accepts a Session or its id.
• activity_type: Only activities of this type.
• exclude_calibration: Excludes calibration and neutral-pose activities. Default True, since these are rarely what you want when browsing a subject's movement history.
• created_after: Only activities created on or after this date (inclusive). Accepts a datetime.date or an ISO YYYY-MM-DD string. A datetime.datetime counts as the day it falls on in its own zone, or in the local one if it carries none.
• created_before: Only activities created on or before this date (inclusive). As created_after.
• search: Free-text search against the activity's name.
• tags: Only activities carrying every tag in this list.
• created_by: Only activities belonging to one of these accounts, by numeric account id.
• only_completed: Only activities whose analysis has finished.
• exclude_analysis_error: Excludes activities whose analysis failed.
• order_by: Field to sort by — one of "created_at", "status", "created_by", "activity_type" — optionally prefixed with "-" for descending. Defaults to "-created_at".
• limit: Caps the total number of activities the stream yields across the whole iteration. Unset iterates every match.

Returns:

An ActivityStream you iterate directly.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If order_by or activity_type isn't recognized, or on request failure or an unexpected response.

Example:

activities = client.activities.list(
    subject=subject,
    activity_type=ActivityType.squats,
    created_after=date(2026, 1, 1),
    order_by="-created_at",
)
for activity in activities:
    print(activity.name)

total = client.activities.list(tags=["study-a"]).total
all_activities = client.activities.list(tags=["study-a"]).all()

Lazily lists subjects matching the given filters.

Arguments:

• search: Free-text search against the subject's name.
• created_after: Only subjects created on or after this date (inclusive). Accepts a datetime.date or an ISO YYYY-MM-DD string. A datetime.datetime counts as the day it falls on in its own zone, or in the local one if it carries none.
• created_before: Only subjects created on or before this date (inclusive). As created_after.
• groups: Only subjects belonging to one of these subject groups.
• tags: Only subjects carrying every tag in this list.
• created_by: Only subjects belonging to one of these accounts, by numeric account id.
• activity_type: Only subjects with at least one activity of this type.
• activity_complete: Only subjects whose activities have (True) or have not (False) all finished analysis.
• session: Only the subject calibrated under this session. Accepts a Session or its id.
• order_by: Field to sort by — one of "name", "created_at", "updated_at" — optionally prefixed with "-" for descending. Defaults to "name".
• limit: Caps the total number of subjects the stream yields across the whole iteration. Unset iterates every match.

Returns:

A SubjectStream you iterate directly.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If order_by or activity_type isn't recognized, or on request failure or an unexpected response.

Example:

subjects = client.subjects.list(search="Falisse", tags=["study-a"])
for subject in subjects:
    print(subject.name)

total = client.subjects.list(tags=["study-a"]).total
all_subjects = client.subjects.list(tags=["study-a"]).all()

Lazily lists sessions matching the given filters.

Arguments:

• subject: Only the session(s) belonging to this subject. Accepts a Subject or its id.
• order_by: Field to sort by — one of "name", "created_at" — optionally prefixed with "-" for descending. Defaults to "-created_at".
• limit: Caps the total number of sessions the stream yields across the whole iteration. Unset iterates every match.

Returns:

A SessionStream you iterate directly.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If order_by isn't recognized, or on request failure or an unexpected response.

Example:

for session in client.sessions.list(subject=subject):
    print(session.id)

total = client.sessions.list(subject=subject).total

Lazily lists subject groups matching the given filters.

Arguments:

• search: Free-text search against the group's name.
• order_by: Field to sort by — currently only "name" — optionally prefixed with "-" for descending. Defaults to "name".
• limit: Caps the total number of groups the stream yields across the whole iteration. Unset iterates every match.

Returns:

A GroupStream you iterate directly.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.
• ModelHealthError: If order_by isn't recognized, or on request failure or an unexpected response.

Example:

for group in client.groups.list(search="cohort"):
    print(group.name)

total = client.groups.list().total

When the group was trashed, or None if it isn't.

Number of subjects in this group.

Whether the group is in the trash.

Display name.

Username of the account that created this group, or None if not reported.

Total activities recorded across every subject in this group.

Freeform description, or an empty string if none was set.

Whether the authenticated account can edit this group.

Unique identifier.

When the group was created.

Whether the authenticated account owns this group.

Timestamp of the most recent activity across the group, or None if there are none.

When the group was last modified.

Name of the current plan, or None when there is no active plan.

Whether the account is on a free trial, or None when there is no organization, or no plan history at all.

Whether recording is currently allowed.

Why recording is blocked, or None when recording_allowed is True.

Activity cap for the current period, or None when there is no active plan, or the plan is unlimited.

Activities consumed in the current period, or None when there is no active plan.

How often activities_used resets, or None when there is no active plan.

Whether the plan will renew automatically at period_end, or None when there is no active plan or no subscription to renew.

When the current billing period ends, or None when there is no active plan.

When this session was last updated.

ID of the subject associated with this session, or None if not set.

A bare ID, not a Subject object.

Activities associated with this session.

ID of the account that owns this session.

When this session was created.

Display name of the session.

Internal session name. Prefer name for display purposes.

Total number of activities in this session.

Unique identifier.

Whether the session is publicly visible.

URL of the QR code image for pairing cameras, or None if not available.

Unique identifier.

Tags applied to this activity.

Raw processing status string. Use ModelHealthClient.activity_status() for the typed value.

Display name, or None if not set.

Recorded video files associated with this activity.

Processed result files associated with this activity.

ID of the parent session.

A bare ID, not a Session object.

Free-text notes attached to the activity, or None if there are none.

Username of the account that owns the parent session, or None if unknown.

The activity type as reported, or None if unset.

Carries {id, name, display_name} through unchanged — including a type this SDK build doesn't recognize.

State of the analysis pipeline: one of "processing", "done", "error", or None when this activity was not loaded through a path that reports it (for example, nested inside a session).

Whether the activity is in the trash.

When this activity was created.

When this activity was last updated.

Unique identifier.

Result tag identifying the content type (e.g. "ik_results", "marker_data").

URL of the result file, or None if not yet available.

ID of the parent activity.

ID of the parent activity.

URL of the video thumbnail, or None if not yet available.

URL of the full video, or None if not yet available.

Unique identifier.

Year of birth, or None if not set.

Height in centimeters, or None if not set.

When this subject record was last modified, or None if not reported.

Unique identifier.

Age in years, or None if not set.

Display name.

Weight in kilograms, or None if not set.

Number of activities recorded for this subject, excluding calibration and neutral trials, or None if not reported.

Free-form tags attached to the subject. Empty rather than missing when unset.

Family name, or None if not reported. Not always available.

Timestamp of the subject's most recent activity, or None if they have none, or if not reported.

Sex assigned at birth as reported, or None if the subject declined to answer or no value is available.

Given name, or None if not reported. Not always available.

Freeform text describing relevant characteristics or medical conditions.

Gender identity as reported, or None if the subject declined to answer or no value is available.

When this subject record was created, or None if not reported.

Display name.

Weight in kilograms.

Height in centimeters.

Sex assigned at birth.

Gender identity.

Freeform text describing relevant characteristics or medical conditions.

Year of birth, or None if not provided.

Machine-readable tag identifier.

Human-readable display label.

Freeform description, when the type carries one. None for a type reported alongside an activity, which carries only the three fields above.

Database id of the activity-type record.

The name a list filters by, e.g. "Squat Exercise".

Whether the type belongs to the account rather than being one everybody has. None for a type reported alongside an activity.

Human-readable label. Not always the same as name — one type reads "Range of Motion (ROM)" and shows as "Custom Activity".

Machine-readable key, e.g. "squat_exercise". What to branch on: it is derived from the name once and then stays put, while name and display_name can both be renamed. Empty when none was reported.

The types everybody has, plus any this account or its organisation added.

The list is the account's own and grows, which is why a list filters by a type taken from here rather than by a name known in advance.

Returns:

Every activity type available to this account.

Raises:

• AuthenticationError: If the API key is invalid or expired.
• NetworkError: On connection failure or timeout.

Example:

types = client.activity_types.list()
squats = next(t for t in types if t.display_name == "Squat Exercise")
for activity in client.activities.list(activity_type=squats):
    print(activity.name)

The type of result data and its implicit file format.

The raw file bytes. Parse according to the format implied by type.

The raw file bytes. Parse according to the format implied by type.

The type of analysis result and its implicit file format.

Unique task identifier.

Create a tagged external result file, validating the extension.

Parameters

• tag: Identifies the data source (e.g. "acme-sensor").
• extension: One of "csv", "json", or "binary".
• data: Raw file bytes.

Raises

• ValueError: If extension is not a supported format.

Visualisation transforms. JSON format.

Inverse-kinematics results. MOT format.

Inverse-kinematics results. CSV format.

Marker trajectories. TRC format.

Marker trajectories. CSV format.

OpenSim musculoskeletal model. OSim format.

Return a tagged motion data descriptor for downloading an externally attached file.

Arguments:

• tag: The tag string used when the file was uploaded.

Returns:

A TaggedMotionDataType that can be passed to ModelHealthClient.motion_data_for_activity().

Computed biomechanical metrics. JSON format.

Analysis report. PDF format.

Raw analysis data. ZIP format.

Original per-camera recordings.

Temporally-synchronised output.

Devices upload recorded video normally.

Devices stop uploading recorded video.

Re-enables uploads, and uploads any videos that were queued locally while disabled.

The subject declined to answer, or no value is available at all — the two are not currently distinguishable through this attribute.

The subject declined to answer, or no value is available at all — the two are not currently distinguishable through this attribute.

No plan is configured for this account.

The current billing period has ended.

The activity cap for the current period has been reached.

The most recent payment attempt failed.

Camera frame rate override. None uses the session default.

Low-pass filter frequency override. None uses the session default.

Checkerboard upright, plane perpendicular to the ground.

Checkerboard flat on the floor, plane parallel to the ground.

No log events are delivered.

Only error-level events.

Warning-level events and above.

All log events, including informational ones.

Account and profile events, such as fetching account info or changing settings.

Activity lifecycle events, such as fetching, updating, or deleting one.

Analysis lifecycle events.

Metrics events, such as fetching dashboard metrics.

Client-level events, such as initialization.

Session, recording, and calibration lifecycle events.

Subject lifecycle events, such as fetching or creating one.

Video download events.

Videos have been uploaded and are being processed.

Processing is complete. The activity is ready for analysis.

Processing failed.

Number of videos successfully uploaded so far.

Total number of videos expected from all cameras.

The analysis task. Pass to ModelHealthClient.analysis_status().

Analysis is in progress.

Analysis completed successfully.

Analysis failed.

Archive is being prepared.

Archive is ready to download.

Archive preparation failed.

All connected cameras are actively recording.

Calibration completed successfully.

Number of videos successfully uploaded so far.

Total number of videos expected from all cameras.

Processing completion percentage (0–100), or None if unavailable.

Number of internal corner rows.

Checkerboard orientation: "perpendicular" or "parallel".

Number of internal corner columns.

Size of each square in millimeters.

Camera frame rate. Default: fps_120.

OpenSim musculoskeletal model. Default: lai_uhlrich_2022.

Scaling pose. Default: upright_standing_pose.

Core processing engine version. Default: v1_0.

Low-pass filter frequency. Default: chosen automatically.

Data-sharing preference. Default: share_processed_data_and_identified_videos.

60 frames per second. Suggested maximum recording duration: 60 s.

120 frames per second (default). Suggested maximum recording duration: 30 s.

240 frames per second. Suggested maximum recording duration: 15 s.

Full-body model with 33 degrees of freedom plus a 6-DoF shoulder complex with a scapulothoracic body and a glenohumeral joint using the ISB-recommended Y-X-Y rotation sequence.

Same full-body model as lai_uhlrich_2022_shoulder without the ISB shoulder complex. Default.

Subject stands straight with feet pointing forward and no bending or rotation at the hips, knees, or ankles. Default.

No posture assumptions. Use when the subject cannot adopt the upright standing pose. Requires all body segments to be visible by at least two cameras.

Version 0.2.

Version 0.3.

Version 1.0 (default).

Share processed data and identified videos (default).

Share processed data and de-identified videos (faces blurred).

Share processed data only. No videos are shared.

Share no data for internal development.

Frequency in Hz.

ID of the newly created session.

Name of the trial whose video is being uploaded.

Number of videos successfully uploaded so far.

Total number of videos to upload.

The measured value, or None if not yet computed.

Right-side measurement, or None if not yet computed.

Left-side measurement, or None if not yet computed.

A MetricValueScalar or MetricValueBilateral instance.

Display name.

Human-readable description, or None if not set.

Metrics within this group.

Display name.

Human-readable description, or None if not set.

Serialize these metrics to a JSON string (snake_case keys, matching the wire format).

Pretty-printed (indented) by default; pass pretty=False for compact output.

Metric groups in display order.

Database ID of the activity type.

UUID of the activity these metrics belong to.