us/obstetric

About

The full read of the study: every still, cine loop and video is read, each frame gets its standard plane, and the best head, abdomen and femur frames are measured; gestational age, EFW, ratios and growth centiles follow.

Endpoint us/obstetric/interpret · version 1.0.0 · $0.08 per request · the bare id us/obstetric 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/obstetric/interpret \
  --header "Authorization: Bearer $MEDRUN_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "input": {
    "files": [
      "file_01K6R4X2Q9Y7T3V5W8Z0A1B2C3"
    ],
    "options": {
      "dating": {
        "ga_days": 245,
        "basis": "lmp"
      },
      "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"
  ],
  "options": {
    "dating": {
      "ga_days": 245,
      "basis": "lmp"
    },
    "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).

• planes Standard planes: The plane of every frame (transthalamic, transventricular and transcerebellar head, AC plane, femur, thorax, maternal cervix, other) with its confidence and the key frame of each plane found.
• biometry Fetal biometry: BPD, OFD and HC on the head plane, TAD, APAD and AC on the abdomen, FL on the femur (outer-to-outer calipers, median of up to three frames each), with the caliper overlay of every measured frame; gestational age by HC (INTERGROWTH-21st) and by HC, AC and FL (Hadlock 1984); EFW (Hadlock 1985, HC-AC-FL); cephalic index, HC/AC, FL/AC and FL/BPD.
• growth Growth centiles: Centiles and z-scores of HC, BPD, OFD, AC and FL (INTERGROWTH-21st fetal growth standards) and of the EFW (Hadlock 1991), with the size-for-gestational-age category (SGA < 10th, AGA, LGA > 90th centile) and the ISUOG work-up recommendation for SGA.
• amniotic-fluid Amniotic fluid: Deepest vertical pocket and amniotic fluid index from quadrant images or a sweep; oligo- and polyhydramnios.
• placenta Placenta: Placental location and distance to the internal os (praevia, low-lying), accreta signs.
• early-pregnancy Early pregnancy: Gestational sac, yolk sac, embryo, cardiac activity, MSD and CRL; intrauterine pregnancy and viability category.
• nt Nuchal translucency: NT, CRL, nasal bone and plane adequacy on the 11–14-week mid-sagittal view.
• fetal-heart Fetal heart screen: Four-chamber, outflow-tract and three-vessel views, cardiothoracic ratio and screening flags.
• anomaly-screen Anomaly screen: ISUOG mid-trimester checklist completion and anomaly flags by region.
• cervix Cervical length: Transvaginal cervical length and funnelling.
• labor-progress Labour progress: Angle of progression, head–symphysis distance and head direction on transperineal images.
• presentation Fetal presentation: Presentation and lie, number of fetuses and cardiac activity from sweeps, including blind sweeps.
• doppler Fetal Doppler: Umbilical artery PI/RI and end-diastolic flow, MCA PI and PSV (MoM), CPR, uterine artery PI.
• report Draft report: Opt-in draft report (findings, impression, limitations) written from the structured result; every number is validated against it.

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