us/echo

About

The full read of the upload: every clip is classified by view and mode, routed to the sections that can use it, and the result contains every section the input supports, the FoCUS answers included.

Endpoint us/echo/interpret · version 1.0.0 · $0.06 up to 1,000 frames · $0.15 up to 8,000 frames · $0.25 above 8,000 frames per request · the bare id us/echo is an alias.

1. Calling the API#

Set up your API key#

Create a key in Settings → API Keys and set it as MEDRUN_KEY in your runtime.

export MEDRUN_KEY="YOUR_API_KEY"

Submit a request#

Every call is asynchronous: submitting returns a request with its id and status, and you follow it until the result is ready.

response=$(curl --request POST \
  --url https://api.medrun.ai/v1/run/us/echo/interpret \
  --header "Authorization: Bearer $MEDRUN_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "input": {
    "files": [
      "file_01K6R4X2Q9Y7T3V5W8Z0A1B2C3"
    ],
    "clinical_context": {
      "sex": "female",
      "height_cm": 165,
      "weight_kg": 70
    },
    "options": {
      "report": false
    }
  }
}')
REQUEST_ID=$(echo "$response" | jq -r .id)

Stream progress#

Stages stream as server-sent events (received, queued, preprocessing, inference, report, completed). Critical findings are flagged first, before the full result.

curl --no-buffer \
  --url https://api.medrun.ai/v1/requests/$REQUEST_ID/events \
  --header "Authorization: Bearer $MEDRUN_KEY" \
  --header "Accept: text/event-stream"

2. Authentication#

The API uses API keys. Send Authorization: Bearer $MEDRUN_KEY with every call. Test keys (mr_test_…) run against the mock backend for free.

API key#

3. Queue#

Fetch request status#

Statuses run queued → preparing → running and end in succeeded, failed, canceled, rejected or expired.

curl --request GET \
  --url https://api.medrun.ai/v1/requests/$REQUEST_ID \
  --header "Authorization: Bearer $MEDRUN_KEY"

Get the result#

When the request has succeeded, output holds the result envelope. See the result format.

curl --request GET \
  --url https://api.medrun.ai/v1/requests/$REQUEST_ID \
  --header "Authorization: Bearer $MEDRUN_KEY" | jq .output

4. Files#

files is a flat list: DICOM files, folders, CD exports (DICOMDIR) and zip/tar archives. The platform groups them into series and runs.

Uploading files#

# 1. Create the upload (one PUT up to 100 MB; larger files get multipart part URLs)
upload=$(curl --request POST --url https://api.medrun.ai/v1/uploads \
  --header "Authorization: Bearer $MEDRUN_KEY" --header "Content-Type: application/json" \
  --data '{"filename": "study.zip", "bytes": 214000000, "media_type": "application/zip"}')
# 2. PUT the bytes to upload.url (with upload.headers)
curl --request PUT --upload-file study.zip "$(echo "$upload" | jq -r .upload.url)"
# 3. Complete it, then pass file.id in input.files
curl --request POST --url "$(echo "$upload" | jq -r .complete_url)" --header "Authorization: Bearer $MEDRUN_KEY"
FILE_ID=$(echo "$upload" | jq -r .file.id)

Hosted files (URL)#

You can also pass https URLs, for example signed S3 or GCS links. MedRun fetches them when the request starts.

5. Webhooks#

Add a webhook to the submit body. MedRun POSTs the request object, signed with Standard Webhooks headers, when the request ends. Configure secrets and see deliveries in Settings → Webhooks.

{
  "input": {
    "files": [
      "file_…"
    ]
  },
  "webhook": {
    "url": "https://example.org/medrun/webhook",
    "events": [
      "request.succeeded",
      "request.failed"
    ]
  }
}

6. Schema#

Input#

Example input:

{
  "files": [
    "file_01K6R4X2Q9Y7T3V5W8Z0A1B2C3"
  ],
  "clinical_context": {
    "sex": "female",
    "height_cm": 165,
    "weight_kg": 70
  },
  "options": {
    "report": false
  }
}

Output#

The output is the MedRun result envelope: sections[] with a status per section, then findings, measurements, scores, classifications, guidance, the optional report and artifacts (DICOM SR/SEG, overlays, PDF, FHIR).

• views Views and image quality: View (PLAX, PSAX, A2C, A3C, A4C, A5C, subcostal, suprasternal) and mode (2D, colour, spectral, M-mode) per clip; clips below the view-confidence gate are named and not measured.
• segment-chambers Chamber segmentation: LV endocardium and epicardium, LA, RV and RA masks on every frame, with areas and volumes.
• lvef LVEF and volumes: LVEF from the apical cine clips (mean of two video networks, recalibrated), EDV and ESV (indexed by BSA), sex-specific ASE ranges, LVEF category and the ASE grade of LV systolic function.
• lv-size LV size and mass: IVSd, LVIDd/s, LVPWd, LV mass and index, relative wall thickness and LV geometry.
• la-volume Left atrial volume: Biplane LA volume at end-systole, LAVi and LA diameter.
• rv-function Right ventricular function: TAPSE, fractional area change, S′, RV basal diameter and RV/LV ratio.
• lv-strain Global longitudinal strain: GLS and the segmental bull's-eye.
• wall-motion Regional wall motion: Per-segment grade, WMSI and coronary territory (AHA 17-segment model).
• diastolic Diastolic function: E, A, E/A, e′, E/e′, TR Vmax, LAVi, diastolic grade and LA pressure estimate.
• valves Valve disease: Aortic stenosis and regurgitation grading from Doppler and 2D.
• pulmonary-hypertension Pulmonary hypertension probability: TR Vmax, RVSP, IVC size and collapse, RA area and the ESC/ERS echo probability.
• pericardial-effusion Pericardial effusion: Presence, size and tamponade signs.
• cardiomyopathy Cardiomyopathy patterns: HCM versus cardiac amyloidosis versus other LVH, LVOT obstruction and dilated pattern.
• focused Focused cardiac ultrasound: FoCUS LV function (normal, reduced, severely reduced) with the EF estimate, and which FoCUS views the upload holds; RV, effusion and IVC answers join with their sections.
• report Draft report: Opt-in draft echo report (findings, impression, limitations) written from the structured result; every number is validated against it.

OpenAPI document: https://api.medrun.ai/v1/models/us/echo/interpret/openapi.json