Downloading the data

Every figure comes with a verified flag. Read the methodology before relying on one that says false.

Your API key

After checkout the key is shown once, on the page you land on. Store it then — we keep only a hash and cannot show it again. Send it as a header:

curl -H "X-API-Key: dk_your_key"   "https://api.providercostreports.com/v1/hospitals/010001/metrics"

Or as ?key= on the URL, which is easier in a browser and worse in a shell history.

Download without touching a terminal

Bulk download

One dataset per file, as CSV or Parquet. The three are kept separate because they are verified differently and a blended file invites treating them as one.

curl -H "X-API-Key: dk_your_key" -OJ   "https://api.providercostreports.com/v1/export?dataset=hospital&format=csv"

-OJ keeps the filename we send, e.g. datakit-hospital-20260822.csv.

format is csv or parquet. Parquet is roughly ten times smaller and keeps verified as a real boolean rather than 0/1. Add &metric=net_patient_revenue to narrow the file to one metric.

What each tier allows

Limits clamp rather than reject. Ask for 5,000 rows on a tier allowing 500 and you get 500 with a header saying so, not an error — so a script written against the wrong tier returns less data rather than breaking.

Other endpoints

GET /v1/hospitals?state=AL&q=mercy&limit=&offset=
GET /v1/hospitals/{ccn}
GET /v1/hospitals/{ccn}/metrics?metric=&from=&to=
GET /v1/metrics?metric=operating_margin&fiscal_year=2024
GET /v1/tiers
GET /v1/health

Responses are JSON. format= is only understood by /v1/export; elsewhere it returns 400 rather than quietly sending JSON to something expecting CSV.

If something goes wrong

402 means the tier does not include what you asked for; the body names the tiers that do. 429 means the daily call budget is spent, and exports have their own separate budget, so one cannot exhaust the other. A key that has lapsed resolves to the free tier rather than failing, so a script keeps running and starts returning one row — check tier in any response if numbers look thin.