> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ochy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first biomechanical analysis in under 5 minutes.

## Prerequisites

* An Ochy partner account with an API key. Contact sales through the [Ochy website](https://www.ochy.io) or from your account to request access.
* 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://partner-api.ochy-prod.com/analysis/start?apiKey=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"
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://partner-api.ochy-prod.com/analysis/start",
      params={"apiKey": "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}")
  ```

  ```javascript JavaScript theme={null}
  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?apiKey=YOUR_API_KEY",
    { method: "POST", body: form }
  );

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

You receive a `202 Accepted` response with a `video_id`:

```json theme={null}
{
  "message": "Analysis started for ID: a1b2c3d4",
  "video_id": "a1b2c3d4"
}
```

## 2. Get results

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

<Tabs>
  <Tab title="Polling">
    Use the `video_id` to check the analysis status. Poll every few seconds until the
    status reaches `success`.

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://partner-api.ochy-prod.com/analysis/a1b2c3d4/results?apiKey=YOUR_API_KEY"
      ```

      ```python Python theme={null}
      import time

      while True:
          result = requests.get(
              f"https://partner-api.ochy-prod.com/analysis/{video_id}/results",
              params={"apiKey": "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)
      ```

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

    While processing, you see `202 Accepted` with status `analyzing`:

    ```json theme={null}
    {
      "video_id": "a1b2c3d4",
      "status": "analyzing",
      "percentage": 45
    }
    ```

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

  <Tab title="Webhooks">
    Instead of polling, you can have Ochy push status updates to your server. First,
    [configure a webhook URL](/guides/webhooks-and-api-keys#from-the-dashboard) from the
    dashboard or via [`PUT /webhook`](/api-reference/webhooks/configure-webhook), then
    pass `notify_via_webhook=true` when starting the analysis:

    ```bash theme={null}
    curl -X POST "https://partner-api.ochy-prod.com/analysis/start?apiKey=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:

    ```json theme={null}
    {
      "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](/guides/webhooks-and-api-keys) for the full event list,
    payload reference, and ordering details.
  </Tab>
</Tabs>

## 3. Get calculated metrics

For structured numerical data, call the calculated data endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://partner-api.ochy-prod.com/analysis/a1b2c3d4/results/calculated_data?apiKey=YOUR_API_KEY"
  ```

  ```python Python theme={null}
  metrics = requests.get(
      f"https://partner-api.ochy-prod.com/analysis/{video_id}/results/calculated_data",
      params={"apiKey": "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")
  ```
</CodeGroup>

Example response for a side view analysis:

```json theme={null}
{
  "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](/guides/analysis-workflow) to understand video
  requirements, analysis types, and the full polling lifecycle.
* Use [subject management](/guides/subject-management) to organize analyses by individual runner.
* Browse the [API reference](/api-reference/analysis/start-analysis) for complete request and response schemas.
* Review [authentication](/authentication) for details on API key management and credits.