Quickstart

Prerequisites

An Ochy account with an API key. Register self-serve at developers.ochy.io: verifying your email grants 1 free analysis credit, so this quickstart costs nothing. See get API access for the full walkthrough.
A short video of a runner (MP4, MOV, AVI, or WEBM — max 30 MB, 10 seconds).

1. Start an analysis

Upload your video and provide basic runner parameters. Replace YOUR_API_KEY with your actual key.

curl -X POST "https://partner-api.ochy-prod.com/analysis/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@runner_side.mp4" \
  -F "analysis_type=side_view" \
  -F "height=1.75" \
  -F "weight=68" \
  -F "language=en" \
  -F "treadmill=false"

import requests

response = requests.post(
    "https://partner-api.ochy-prod.com/analysis/start",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"video": open("runner_side.mp4", "rb")},
    data={
        "analysis_type": "side_view",
        "height": 1.75,
        "weight": 68,
        "language": "en",
        "treadmill": "false",
    },
)

data = response.json()
video_id = data["video_id"]
print(f"Analysis started: {video_id}")

const form = new FormData();
form.append("video", fs.createReadStream("runner_side.mp4"));
form.append("analysis_type", "side_view");
form.append("height", "1.75");
form.append("weight", "68");
form.append("language", "en");
form.append("treadmill", "false");

const response = await fetch(
  "https://partner-api.ochy-prod.com/analysis/start",
  {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_API_KEY" },
    body: form,
  }
);

const { video_id } = await response.json();
console.log(`Analysis started: ${video_id}`);

You receive a 202 Accepted response with a video_id:

{
  "message": "Analysis started for ID: a1b2c3d4",
  "video_id": "a1b2c3d4"
}

2. Get results

There are two ways to receive analysis results: polling or webhooks.

Polling
Webhooks

Use the video_id to check the analysis status. Poll every few seconds until the status reaches success.

curl "https://partner-api.ochy-prod.com/analysis/a1b2c3d4/results" \
  -H "Authorization: Bearer YOUR_API_KEY"

import time

while True:
    result = requests.get(
        f"https://partner-api.ochy-prod.com/analysis/{video_id}/results",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    ).json()

    print(f"Status: {result['status']} ({result.get('percentage', 0)}%)")

    if result["status"] == "success":
        break
    if result["status"] == "failed":
        raise Exception("Analysis failed")

    time.sleep(3)

let result;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const res = await fetch(
    `https://partner-api.ochy-prod.com/analysis/${video_id}/results`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  result = await res.json();
  console.log(`Status: ${result.status} (${result.percentage ?? 0}%)`);
} while (result.status !== "success" && result.status !== "failed");

While processing, you see 202 Accepted with status analyzing:

{
  "video_id": "a1b2c3d4",
  "status": "analyzing",
  "percentage": 45
}

When complete, the response includes the full biomechanical analysis, signed URLs for the annotated video and thumbnail.

Instead of polling, you can have Ochy push status updates to your server. First, configure a webhook URL in the developer portal or via PUT /webhook, then pass notify_via_webhook=true when starting the analysis:

curl -X POST "https://partner-api.ochy-prod.com/analysis/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@runner_side.mp4" \
  -F "analysis_type=side_view" \
  -F "height=1.75" \
  -F "weight=68" \
  -F "notify_via_webhook=true"

Ochy sends POST requests to your endpoint as the analysis progresses:

{
  "analysis_id": "a1b2c3d4",
  "event_type": "analysis.completed",
  "status": "success",
  "percentage": 100,
  "sequence": 11,
  "timestamp": "2026-03-23T10:46:30Z"
}

Your endpoint should respond with a 2xx status and process the payload in the background. See the API keys and webhooks guide for the full event list, payload reference, and ordering details.

3. Get calculated metrics

For structured numerical data, call the calculated data endpoint:

curl "https://partner-api.ochy-prod.com/analysis/a1b2c3d4/results/calculated_data" \
  -H "Authorization: Bearer YOUR_API_KEY"

metrics = requests.get(
    f"https://partner-api.ochy-prod.com/analysis/{video_id}/results/calculated_data",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()

print(f"Speed: {metrics['metrics']['speed_meter_per_second']} m/s")
print(f"Cadence: {metrics['metrics']['step_frequency_steps_per_min']} spm")

Example response for a side view analysis:

{
  "metrics": {
    "speed_meter_per_second": 2.123,
    "step_length_meter": 1.15,
    "pace_min_per_km": 7.511,
    "step_frequency_steps_per_min": 110,
    "ground_contact_time_ms": 280,
    "time_of_flight_ms": 120
  },
  "overstride": {
    "mean_angle": 3.47,
    "score": "score_good"
  },
  "total_score": 0.588
}

Next steps

Read the analysis workflow guide to understand video requirements, analysis types, and the full polling lifecycle.
Use subject management to organize analyses by individual runner.
Browse the API reference for complete request and response schemas.
Review authentication for details on API key management and credits.

Getting started

Guides

Prerequisites

1. Start an analysis

2. Get results

3. Get calculated metrics

Next steps

​Prerequisites

​1. Start an analysis

​2. Get results

​3. Get calculated metrics

​Next steps

Prerequisites

1. Start an analysis

2. Get results

3. Get calculated metrics

Next steps