API

Send the key as a bearer token. That is the whole setup.

curl "https://data.soro.health/v1/rates/compare?system=DRG&code=470" \
  -H "Authorization: Bearer $SORO_API_KEY"

const res = await fetch(
  "https://data.soro.health/v1/rates/compare?system=DRG&code=470",
  { headers: { Authorization: `Bearer ${process.env.SORO_API_KEY}` } },
);
const data = await res.json();

import os, requests

r = requests.get(
    "https://data.soro.health/v1/rates/compare",
    params={"system": "DRG", "code": "470"},
    headers={"Authorization": f"Bearer {os.environ['SORO_API_KEY']}"},
)
data = r.json()

• Base URLhttps://data.soro.health/v1
• Lists{"object":"list","items":[…],"page":{…}}. Pass cursor= to fetch the next page.
• AmountsPlain USD numbers, never strings.
• Server-side onlyThe API sends no CORS headers, on purpose: a key in browser code is a leaked key.
• Every responseX-Request-Id, X-Api-Version, X-RateLimit-*.

Reads use GET and jobs use POST. Each group of endpoints needs one scope.

Percent of charges. Some hospitals price a code as a percent of billed charges rather than as a dollar amount. Where one does, /v1/rates/compare and the MCP compare_rates tool add a pctOfCharge object beside low/median/high. pct and gross are one pair the hospital filed together on the same rows, the pair it files most often for that code. pairRows counts the rows carrying that pair, rows counts every row of the file that states a percent for the code, and pairs counts how many different pairings it files. Those counts cover every row of the hospital's file whose percent cell holds a valid percent (a number above 0 and at most 100), not a filtered subset, because they are what the pair is described against. A null gross means no dollar amount may be estimated at all, and tied above 1 means the file holds that many pairings filed on the same top number of rows, so the file does not say which pairing applies. note repeats the rule in the payload: these are filed inputs, and their product is an estimate, never a filed rate. Nothing computed from them enters a statistic, a benchmark or an export here.

For keys below Market Analytics the figures are withheld and the object carries available and estimable instead. estimable is not a figure, so every key receives it: true means the hospital files a charge on the same rows as the percent, so a dollar amount can be estimated from the pair; false means it files no charge that may be multiplied, so the percent stands alone and no plan will show an estimate. Keys on Market Analytics receive it too, as a one-boolean summary of what a null gross means. The withheld object also carries its own note saying the same thing in words, so a caller never offers its user a dollar amount that does not exist.

Answers "can you run these codes at these hospitals" in one call. You can paste codes the way they are actually written (with procedure names, parentheses, slash-paired codes, or one per line) and name hospitals the way you know them rather than the name in the file. Pass format=csv for a downloadable spreadsheet.

curl -G "https://data.soro.health/v1/rates/batch" \
  --data-urlencode "codes=Septoplasty (30520), Tympanoplasty (69631), Tympanostomy tubes (69433/69436)" \
  --data-urlencode "hospitals=St. Joseph's Syracuse, St. Peter's Albany" \
  --data-urlencode "format=csv" \
  -H "Authorization: Bearer $SORO_API_KEY" -o rates.csv

Every pairing gets a row, including the ones with no rates: on_file: no answers "does this hospital price this code at all", which is often half the question. A hospital name that matches nothing, or matches two different facilities, comes back under unmatched with the candidates named; we never substitute a match silently. Each row names its source: corpus (our aggregated multi-hospital index, which also carries the market percentile) or direct-export (taken from that hospital's own price file). A facility that appears in both sources counts as one hospital, not an ambiguity, and the entry we serve says so under alsoNamed.

Each synchronous call takes up to 25 codes and 12 hospitals. A hospital named twice uses one slot, and anything past a limit comes back by name under dropped, in the JSON and as rows in the CSV, so a call is never trimmed without saying so. For more, queue a job: up to 5,000 codes by 500 hospitals.

A job asks the same question as a synchronous call, without its size limit, and writes the answer to files: you queue it, poll it and download the result. Jobs need the write:jobs scope and a key on Market Analytics (or a sandbox key).

POST /v1/jobs      {"kind":"batch","spec":{"system":"CPT","codes":[…≤5000],"hospitals":[…≤500],"format":"csv|json|ndjson|parquet"}}
POST /v1/exports   {"source":"provider_rates|hospital_rates|hospitals","format":"csv|ndjson|json","system":"CPT","codes":[…]|"family":"…","states":[…]}
GET  /v1/jobs?status=&limit=          →  {"object":"list","items":[job…]}
GET  /v1/jobs/{id}                     →  {"object":"job","status":"queued|running|done|failed|cancelled","progress":0.42,
                                            "result":{"rows":123456,"files":[{"name":"batch.csv","bytes":…,"sha256":"…","url":"https://…"}]}}
POST /v1/jobs/{id}/cancel

• 202 when queuedThe response body is the job; poll it. Once a job is done, failed or cancelled, its status never changes.
• LinksA fresh result.files[].url is issued on every read and expires after ten minutes; the stored job holds storage paths, never URLs. Use sha256 to verify the file.
• Plan at run timeWe check the owner's plan when the job runs, not when it was queued. If it has dropped below Market Analytics by then, the results come back without dollar figures.
• Kindsbatch and export run here; dataset and delivery are passed to the dataset builder and answer with its job id.
• WebhookSubscribe to job.completed on /webhooks to be notified instead of polling.
• In the appThe same queue is on /jobs.

Every dated revision, newest first. GET /v1/changelog returns the same list.