search
WebsitePlatform

Running

hashtag
Create a New Video Processing Session

post

This endpoint allows an admin (or sub-admin) to upload a video file for processing and create a new "session" resource on behalf of another user. The server will return a session_id that can be used to poll or retrieve the session details/results.

hashtag
Request Body (Multipart/Form-Data)

You must supply the following fields:

  • user_id (string, required): The ID of the user on whose behalf this session is created.

  • video (file, required): The raw video file to be processed.

  • session_name (string, optional): A human-readable name/title for the session.

  • incline_degree (string or number, optional): Numeric value representing the incline degree.

  • body_joint_angles (array[string], optional): A comma-separated list of joint names (e.g. 'elbow, knee, ankle'). Defaults to ['all'] if not provided.

hashtag
Response Structure

On success (HTTP 200), the response is a JSON object with:

  • session_id (string): A unique identifier for the created session.

  • title (string): The session title (defaults to a fallback if session_name was not provided).

hashtag
Workflow

  1. POST a multipart/form-data request containing the required fields user_id and video, plus any optional fields.

  2. Provide A valid API-KEY token in the Authorization header.

  3. The caller must have admin privileges to successfully create a session for another user.

  4. If successful, the server responds with session_id and title.

  5. If an error occurs (e.g., missing fields, lack of permissions), a JSON object with an error key is returned.

Example cURL:

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Body
user_idstringRequired

Required. The ID of the user for whom this session is created (form field: text).

videostringRequired

Required. The raw video file to be processed (form field type: file).

session_namestringOptional

Optional. A descriptive name for the session (form field: text).

incline_degreestringOptional

Optional. A numeric string indicating the incline degree (form field: text).

body_joint_anglesarrayOptional

Optional. A comma-separated list of joint names. Available values: 'ankle', 'knee', 'elbow', 'hip', 'shoulder'. Example: ankle,knee,hip

Responses
post
/running/sessions/

hashtag
Retrieve Running Session Details

get

Retrieves detailed information for a specific running session identified by the session_id.

hashtag
Path Parameter

  • session_id (string, required): The unique identifier of the session to retrieve.

hashtag
Query Parameter

  • demo (boolean, optional): Set to true to retrieve the demo running session data instead of a real one.

hashtag
Response Structure

On success (HTTP 200), the response is a JSON object containing the following fields:

  • metrics (object): A dictionary of metric arrays (e.g., speed, cadence, distance). Each key maps to an array of numbers.

  • angles (object): A dictionary of angle arrays (e.g., lhip_angle, rsho_angle). Each key maps to an array of numbers.

  • all_timestamps (array[number]): A list of timestamps (in seconds) for the session data.

  • analyzed_video_url (string, URI): The URL for the analyzed video (with keypoints overlay).

  • video_url (string, URI): The URL for the original uploaded video.

  • segments (integer): The number of segments processed.

  • created_at (object): An object containing:

    • date (string): The creation date in DD/MM/YYYY format.

    • time (string): The creation time in HH:MM AM/PM format.

  • user_name (string): The name of the user associated with the session.

  • activity (string): The activity type (e.g., 'Running').

  • title (string): The title of the session.

  • calculated_metrics (object): A dictionary containing computed statistics (such as averages, minima, and maxima) for various metrics.

  • summary (string): An optional textual summary of the session.

hashtag
Error Handling

  • 400 Bad Request: The request parameters are invalid (e.g., invalid admin UID).

  • 401 Unauthorized: The access token is missing or invalid.

  • 403 Forbidden: The user does not have sufficient privileges to access the session.

  • 404 Not Found: The session does not exist or is not valid for the specified activity.

  • 500 Internal Server Error: An unexpected server-side error occurred.

hashtag
Security

A valid API-KEY token must be provided in the Authorization header.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the demo running session data instead of a real one.

Responses
get
/running/sessions/{session_id}/

hashtag
Get Summary of a Running Session

get

Retrieve a detailed summary of a running session using its unique session_id. This summary includes both quantitative performance metrics and an optional qualitative summary generated by GenAI if available.

Usage Instructions:

  1. Send a GET request with the session_id in the path parameter.

  2. The endpoint will return a JSON object that includes various sections of the session summary.

hashtag
Query Parameter

  • demo (boolean, optional): Set to true to retrieve a pre-generated demo summary for this running session.

Response Structure:

  • summary_text (object, optional): Contains GenAI-generated commentary if available. This object may include the following keys:

    • balance_and_posture: Comments on the athlete's balance and posture (e.g. suggestions to improve running balance).

    • performance_metrics: Overall performance comments such as changes in speed, cadence, and power output.

    • running_mechanics: Observations on running form, including contact time, flight time, stride time, and stride length.

    • final_summary: A final overall assessment remark summarizing the session performance.

    • distance_and_duration: Comments on the total distance covered and session duration.

  • performance_metrics (object): Contains aggregated performance metrics with their minimum, maximum, average values, and the raw data as an array, covering the following:

    • speed (in m/s)

    • pace (in min/km)

    • cadence (steps/min)

    • power (in Watts)

    • normalized_power (in W/kg)

  • running_mechanics (object): Contains the following running mechanics data:

    • contact_time (in seconds)

    • flight_time (in seconds)

    • stride_time (in seconds)

    • stride_length (in meters)

    • footstrike: A string describing the most common footstrike type (e.g. 'forefoot').

  • balance_and_posture (object): Contains metrics related to balance and posture:

    • balance: Includes minimum, maximum, average, and array of balance scores.

    • contact_angle: Includes the minimum, maximum, average, and array of contact angle values (in degrees).

  • distance_and_duration (object): Contains raw values for:

    • total_distance (in meters)

    • total_time (in seconds)

  • user_information (object): Contains detailed user data, including:

    • ycom: User's YCOM value

    • weight: User's weight in kilograms

    • age: User's age

    • height: User's height in centimeters

    • leg_length: User's leg length

    • shoeSize: User's shoe size

    • gender: User's gender

    • user: The unique user ID

    • brand: Shoe brand information (if any)

    • shoeModel: Shoe model information (if any)

    • email: User's email address

    • display_name: User's display name

  • session_date (string): The date of the session in a formatted string (e.g. 'DD/MM/YYYY').

Note: The summary_text field will only be present if GenAI-generated summary comments have been saved for the session.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve a pre-generated demo summary for this running session.

Responses
get
/running/sessions/{session_id}/summary/

hashtag
Generate Summary for a Running Session

post

Trigger the generation of summary threads for a running session. This endpoint creates separate summary threads for each summary block based on session metrics, including performance metrics, running mechanics, balance and posture, and distance/duration, as well as a final overall summary. Returns a JSON object containing thread IDs for each summary block.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Query parameters
measurement_systemstring Β· enumOptional

Measurement system: 'metric' or 'imperial'

Possible values:
Responses
post
/running/sessions/{session_id}/summary/

hashtag
Export Running Session Data

get

Retrieves detailed session data for exporting a specific running session identified by the session_id.

hashtag
Path Parameter

  • session_id (string, required): The unique identifier of the session to export.

hashtag
Query Parameter

  • demo (boolean, optional): Set to true to retrieve the pre-generated demo running session instead of a real one.

hashtag
Response Structure (HTTP 200)

The response is a JSON object that includes:

  • metrics (object): A dictionary where each key represents a metric (e.g., 'speed', 'cadence') and its value is an array of numbers.

  • keypoints (object): A dictionary where each key represents a keypoint (e.g., 'lknev', 'ltoev') and its value is an array of numbers.

  • angles (object): A dictionary where each key represents an angle (e.g., 'lelb_angle', 'lhip_angle') and its value is an array of numbers.

  • all_timestamps (array[number]): An array of timestamps (in seconds) corresponding to the data points.

  • contact (array[boolean]): An array of boolean values indicating contact status.

  • activity (string): The activity type (e.g., 'Running').

hashtag
Error Handling

  • 400 Bad Request: The request parameters are invalid (e.g., an invalid admin UID).

  • 401 Unauthorized: The access token is missing or invalid.

  • 403 Forbidden: The user does not have sufficient privileges to access this session data.

  • 404 Not Found: The requested session does not exist or is invalid for the activity.

  • 500 Internal Server Error: An unexpected server error occurred.

hashtag
Security

A valid API-KEY token must be provided in the Authorization header.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the pre-generated demo running session instead of a real one.

Responses
get
/running/sessions/{session_id}/export/

hashtag
Running-Form Analysis Report

post

Retrieves a detailed running-form analysis report for a given session. The endpoint requires the user to have a valid admin token and an active subscription plan (Pro, Premium, Enterprise, or Standard).

hashtag
Request

  • Path Parameter:

    • session_id (string, required): The unique identifier of the session for which the running-form analysis report is requested.

  • Query Parameter:

    • demo (boolean, optional): Set to true to retrieve a pre-generated demo running-form analysis report instead of a real one.

hashtag
Response Structure (HTTP 200)

The response is a JSON object containing:

  • metrics (object): Stride-averaged values such as speed, balance, cadence, contact_angle, eversion_velocity, knee_flexion, posture_angle, ankle_angle, com_oscillation, stride_angle, mean_h.

  • images (object): Three representative snapshots keyed contact_angle, push_angle, knee_ankle; each value is a public image URL.

  • user_info (object): Information about the user who submitted the session, including:

    • age (integer)

    • gender (string)

    • height (number, cm)

    • weight (number, kg)

    • email (string, email)

    • uid, display_name, admin_name, last_session, phone, brand, shoeModel, shoeSize, leg_length, ycom (various types)

  • form_comments (object, optional): GenAI recommendations for blocks contact_angle, hip_extension_at_foot_takeoff, foot_contact_angle_and_torso_lean.

  • date (string): The date the report was generated in DD/MM/YYYY format.

hashtag
Error Handling

  • 400 Bad Request: Invalid token or parameters.

  • 401 Unauthorized: Token is missing or invalid.

  • 403 Forbidden: Admin access is required.

  • 404 Not Found: The session was not found or the user does not have a valid payment plan.

  • 500 Internal Server Error: An unexpected error occurred on the server.

hashtag
Security

A valid API-KEY token must be provided in the Authorization header.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve a pre-generated demo running-form analysis report instead of a real one.

Responses
post
/running/sessions/{session_id}/form-analysis/

hashtag
Retrieve Total Metrics

get

Calculates and returns the average metrics for all running sessions of the admin user, along with the detailed metrics and creation timestamp of the most recent session.

hashtag
Response Structure (HTTP 200)

The response is a JSON object with the following structure:

  • avg_metrics (object): Contains the average values calculated across all sessions.

    • avg_speed (number): Average speed.

    • avg_power (number): Average power.

    • avg_cadence (number): Average cadence.

    • avg_flight_time (number): Average flight time.

  • last_session_metrics (object): Contains detailed metrics for the most recent session.

    • speed (object): Speed metrics with:

      • avg (number): Average speed.

      • min (number): Minimum speed.

      • max (number): Maximum speed.

    • normalized_power (object): Normalized power metrics with keys avg, min, max.

    • cadence (object): Cadence metrics with keys avg, min, max.

    • total_distance (number): Total distance.

    • power (object): Power metrics with keys avg, min, max.

    • stride_time (object): Stride time metrics with keys avg, min, max.

    • total_time (number): Total session time.

    • contact_time (object): Contact time metrics with keys avg, min, max.

    • contact_angle (object): Contact angle metrics with keys avg, min, max.

    • incline (object): Incline metrics with keys avg, min, max.

    • pace (object): Pace metrics with keys avg, min, max.

    • stride_length (object): Stride length metrics with keys avg, min, max.

    • rbalance (object): Balance metrics with keys avg, min, max.

    • flight_time (object): Flight time metrics with keys avg, min, max.

    • footstrike (string): The footstrike type (e.g., 'midfoot').

  • last_session_created_at (object): The creation timestamp of the most recent session, containing:

    • date (string): Date in DD/MM/YYYY format.

    • time (string): Time in HH:MM AM/PM format.

hashtag
Error Handling

  • 400 Bad Request: Invalid request parameters (e.g., invalid admin UID).

  • 401 Unauthorized: Missing or invalid access token.

  • 403 Forbidden: Insufficient privileges to retrieve total metrics.

  • 404 Not Found: No sessions found or metrics unavailable.

  • 500 Internal Server Error: An unexpected error occurred on the server.

hashtag
Security

A valid API-KEY token must be provided in the Authorization header.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Responses
get
/running/sessions/metrics/total/

hashtag
Create Form-Analysis Comment Threads

post

Generate GenAI threads that produce personalised commentary for each running-form block (contact-angle, hip-extension at foot take-off, foot-contact angle & torso lean) plus an overall recommendation. Returns a mapping from block keys to thread IDs.

hashtag
Request

  • session_id (path parameter, required): The ID of the running session for which to generate comment threads.

hashtag
Response (201)

A JSON object mapping each form block key to its corresponding GenAI thread ID:

  • contact_angle: Thread ID for the contact angle block.

  • push_angle: Thread ID for the push angle block.

  • knee_ankle: Thread ID for the knee-ankle block.

  • general_form_recommendation: Thread ID for the overall form recommendation.

hashtag
Error Handling

  • 403 Forbidden: User lacks a valid payment plan.

  • 404 Not Found: Session not found or retrieval error.

  • 500 Internal Server Error: Unexpected server error.

hashtag
Security

Requires A valid API-KEY token or API key in the request headers.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Responses
post
/running/sessions/{session_id}/form-recommendations/

hashtag
Gait Analysis Report

post

Retrieves a detailed gait analysis report for a given session. The endpoint requires the user to have a valid admin token and an active subscription plan (Pro, Premium, Enterprise, or Standard).

hashtag
Request

  • Path Parameter:

    • session_id (string, required): The unique identifier of the session for which the gait analysis report is requested.

  • Query Parameter:

    • demo (boolean, optional): Set to true to retrieve a pre-generated demo gait analysis report instead of a real one.

hashtag
Response Structure (HTTP 200)

The response is a JSON object containing:

  • left (object) and right (object): Each side contains gait analysis data with the following fields:

    • peak_time (number): The peak time value identified in the gait analysis.

    • initiator (string): Indicates which side initiated the gait cycle.

    • phases (object): An object with named phases (e.g., flight, takeoff, mid_stance, strike, new_strike), where each phase contains:

      • video_frame (integer): The corresponding video frame.

      • graph_phase (integer): The phase value used in graphs.

      • video_phase (integer): The phase value in video timeline.

      • image_url (string, URI): Public image URL for the phase snapshot.

    • angles (object): Angle measurements for joints like posture_angle, lhip_angle, etc. Each includes:

      • current (array[number]): Current frame angle values.

      • next (array[number]): Next predicted values.

      • std_dev (array[number]): Standard deviation values.

    • graph_timestamps (array[number]): Timestamps (ms) aligned with graph data.

  • user_info (object): Information about the user who submitted the session, including:

    • age (integer)

    • gender (string)

    • height (number, cm)

    • weight (number, kg)

    • email (string, email)

    • uid, display_name, admin_name, last_session, session_count, phone, brand, shoeModel, shoeSize, leg_length, ycom (various types)

  • report_comments (object, optional): Suggestions or notes for angles such as right_posture_angle, left_knee_angle, etc.

  • date (string): The date the report was generated in DD/MM/YYYY format.

hashtag
Error Handling

  • 400 Bad Request: Invalid token or parameters.

  • 401 Unauthorized: Token is missing or invalid.

  • 403 Forbidden: Admin access is required.

  • 404 Not Found: The session was not found or the user does not have a valid payment plan.

  • 500 Internal Server Error: An unexpected error occurred on the server.

hashtag
Security

A valid API-KEY token must be provided in the Authorization header.

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve a pre-generated demo gait analysis report instead of a real one.

Responses
post
/running/sessions/{session_id}/gait-analysis/

hashtag
Create Gait Analysis Recommendations Threads

post

hashtag
Create Gait Analysis Recommendations Threads

This endpoint generates personalized recommendation threads for a specific session based on the user's running gait analysis. Each thread offers biomechanical insights, posture tips, and training guidance for different joint angles.

Usage Example: Send a POST request to /running/sessions/{session_id}/recommendation/ where {session_id} is the session’s unique identifier.

Parameters:

  • session_id (string, required): The unique ID of the session to generate threads for.

Response Structure (HTTP 201): Returns a JSON object mapping each gait angle metric to a thread ID, including both left and right sides:

  • left_posture_angle, left_hip_angle, left_knee_angle, left_ankle_angle

  • right_posture_angle, right_hip_angle, right_knee_angle, right_ankle_angle

Notes:

  • The session must be valid and correspond to a gait analysis report.

  • Requires an active payment plan (Pro, Premium, Enterprise, or Standard).

Authorizations
AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters
session_idanyRequired
Responses
post
/running/sessions/{session_id}/recommendation/
PreviousAnalyzed videoNextJumping

Last updated

Was this helpful?