CMS Hospital Price Transparency Negotiated Payer Rates Scraper

Pull payer-specific negotiated rates, cash prices, gross charges and de-identified min/max rates for the procedure codes you choose, straight from the price transparency files that U.S. hospitals must publish under 45 CFR Part 180.

What it does

• Takes hospital root domains (for example https://www.uhhospitals.org), fetches each hospital's /cms-hpt.txt pointer file, and resolves it to the standard-charges Machine-Readable File (MRF). You can also pass direct MRF URLs.
• Streams each MRF without downloading it to disk. Files run from about 50 MB to 8 GB. Supported formats: CMS v2.0 and v3.0 JSON, gzip-compressed JSON (detected by magic bytes, not file extension), CSV in both the "tall" and "wide" CMS layouts, and single-file ZIP archives. CMS template v3.0 files (the current template, in effect since 2026-01-01) are supported and verified against live hospital files.
• Checks each file's header block (hospital name, last-updated date, version) before extracting anything. A missing or restructured header fails that hospital loudly as structure drift.
• Validates the fields the output depends on, not just the header. If a file renames the payer key inside payers_information (or the payer_name column in a tall CSV), renames or empties the item description, carries a price value that is present but cannot be parsed as a number, or uses a care setting outside inpatient / outpatient / both, the affected hospital fails loudly or the affected rows are counted and dropped, and the run reports PARTIAL: (or fails that hospital) with the count and the reason named. Drift never ships as a silent Complete:.
• Matches both the billing code and its code type. 27447 only matches records typed CPT or HCPCS, never a chargemaster (CDM), revenue code (RC) or DRG record that happens to share the same digits.
• Filters by payer name keywords and care setting (inpatient, outpatient or both).
• Reports scanned vs matched vs delivered rows and how much of each file was scanned in the run status, so caps and time budgets are always visible. A hospital that hits the scan budget or the row cap stops as a per-hospital PARTIAL: naming the cap; a hospital whose file structure has drifted fails that hospital loudly with the reason named.

Who it's for

• Self-funded employers, benefits consultants and TPAs comparing what different insurers pay a hospital for the same procedure.
• Health plans and provider network teams benchmarking negotiated rates in a market.
• Healthcare analysts and journalists studying price variation between hospitals and payers.

Input

Example input. The example run options use a default maximum charge of $50 ("maxTotalChargeUsd": 50).

{
  "hospitalMrfUrlsOrDomains": ["https://www.uhhospitals.org"],
  "billingCodesFilter": ["27447", "45378", "70553", "99285"],
  "payerNameKeywords": ["Aetna", "UnitedHealthcare", "Cigna", "Blue Cross"],
  "settingFilter": "BOTH",
  "maxRowsPerHospital": 5000,
  "maxMrfFilesPerDomain": 1,
  "maxScanSecondsPerFile": 1800,
  "maxItems": 1000
}

Field	Description
hospitalMrfUrlsOrDomains	Hospital domains (resolved via /cms-hpt.txt) or direct MRF URLs.
billingCodesFilter	Plain 5-character codes match CPT/HCPCS; letter + 4 digits match HCPCS; 3 digits match MS-DRG. Use TYPE:CODE for anything else, e.g. APR-DRG:540.
payerNameKeywords	Case-insensitive; spaces and punctuation are ignored. Empty = all payers plus cash-only rows.
settingFilter	INPATIENT, OUTPATIENT or BOTH. Charges marked "both" are included in either setting.
maxRowsPerHospital	Row cap per MRF file, honored exactly.
maxMrfFilesPerDomain	Health systems often list one file per location. Only the first N unique files per domain are scanned.
maxScanSecondsPerFile	Streaming time budget per file, at most 1800 (the 30 minute per-hospital processing cap). Lower it for a quicker partial scan; a file that hits the budget is reported as a per-hospital PARTIAL naming the cap.
maxItems	Total row cap for the run.

Output

Field	Type	Description
hospitalName	string	Hospital name from the MRF header
cmsCertificationNumberCcn	string|null	Facility identifier from the MRF header. MRFs have no CCN field, so this holds the reported state license (LICENSE-OH:1497) or, if missing, the Type 2 NPI (NPI:1609189604)
lastUpdatedDate	string	File's last-updated date (YYYY-MM-DD)
billingCodeType	string	CPT, HCPCS, MS-DRG, etc.
billingCode	string	The matched code
procedureDescription	string	Hospital's description of the item or service
careSetting	string	INPATIENT, OUTPATIENT or BOTH
grossChargeUsd	number|null	Chargemaster gross charge
discountedCashPriceUsd	number|null	Self-pay discounted cash price
payerName	string|null	Insurer name
planName	string|null	Plan or product name
negotiatedDollarRateUsd	number|null	Payer-specific negotiated dollar amount
negotiatedMethodology	string|null	fee schedule, case rate, per diem, percent of billed charges, etc. When no dollar amount exists, the hospital's algorithm text is appended
deidentifiedMinRateUsd	number|null	De-identified minimum negotiated charge
deidentifiedMaxRateUsd	number|null	De-identified maximum negotiated charge
billingClass	string|null	facility or professional
modifiers	string|null	Code modifiers on the charge (e.g. TC, 26)
sourceMrfUrl	string	The MRF actually streamed, after cms-hpt.txt resolution

What is not emitted

• Percentage-based negotiated charges carry no rate value. When a hospital publishes a negotiated charge only as a percentage (a standard_charge_percentage / negotiated_percentage value with a methodology such as "percent of billed charges") and no dollar amount, the row is still emitted, with negotiatedDollarRateUsd set to null. The percentage value itself is not emitted in any output field. negotiatedMethodology still carries the methodology text the hospital published, so these rows are identifiable.
• CMS v3.0 allowed amounts are not surfaced. The CMS v3.0 template adds allowed-amount elements to negotiated charges (the median allowed amount, the 10th percentile and 90th percentile allowed amounts, and a count of allowed amounts). This Actor does not emit those elements; no output field carries them.

Sample row (synthetic)

{
  "hospitalName": "Example Valley Medical Center",
  "cmsCertificationNumberCcn": "LICENSE-OH:0000",
  "lastUpdatedDate": "2026-07-01",
  "billingCodeType": "CPT",
  "billingCode": "27447",
  "procedureDescription": "TOTAL KNEE ARTHROPLASTY",
  "careSetting": "OUTPATIENT",
  "grossChargeUsd": 48250.0,
  "discountedCashPriceUsd": 36190.0,
  "payerName": "Example Health Plan",
  "planName": "Commercial PPO",
  "negotiatedDollarRateUsd": 21400.0,
  "negotiatedMethodology": "case rate",
  "deidentifiedMinRateUsd": 15800.0,
  "deidentifiedMaxRateUsd": 31250.0,
  "billingClass": "facility",
  "modifiers": null,
  "sourceMrfUrl": "https://www.example.com/price-transparency/000000000_example-valley-medical-center_standardcharges.json"
}

How pricing works

Pay per result. You only pay for rows returned.

Data source and terms

• Source: each hospital's own standard-charges file, published under the CMS Hospital Price Transparency rule (45 CFR Part 180) and located through its /cms-hpt.txt pointer file. See CMS Hospital Price Transparency.
• Update frequency: hospitals must update their files at least once a year; many update monthly or quarterly. Each row carries the file's own lastUpdatedDate.
• Data is returned as the hospital published it. This Actor does not correct or audit hospital pricing.
• This Actor is not affiliated with or endorsed by CMS, HHS or any hospital.

Limits and FAQ

• Large files take time. A 3.5 GB CSV takes several minutes to stream end to end. The default budget is the full 30 minute per-hospital cap; the run status shows rows scanned, matched and delivered plus how many MB of each file were scanned. Lower maxScanSecondsPerFile for a quicker partial scan, which is reported as PARTIAL.
• Multi-location systems. University Hospitals lists 14 locations covering 13 unique files in its cms-hpt.txt (one file serves two locations; duplicates are de-duplicated). Raise maxMrfFilesPerDomain to scan more of them, or pass specific MRF URLs.
• Blocked or missing files. If a hospital's pointer file or MRF can't be reached, returns HTML, or uses an unsupported format, that hospital is reported by name in a PARTIAL: status while the other hospitals still deliver rows.
• Multiple rates for one payer. Hospitals often list several rates for the same payer and code (different modifiers, billing classes or settings). Check modifiers, billingClass and careSetting.
• No personal data. Contact names and emails inside cms-hpt.txt are never output.
• Found a problem or need a field? Open an issue on the Issues tab; we respond quickly.

Changelog

• v0.1.3: Red Team final-GO fix round. The JSON payer sentinel now fires on every scan exit path, not only after a full scan: the per-hospital row cap, both scan-time-budget exits, an interrupted stream, and normal completion all evaluate it. A renamed payer_name key inside payers_information therefore fails that hospital as structure drift at any file size and on any exit path, with the Issues CTA, and rows built from payers_information entries are dropped instead of being delivered with a null payer name. Rows from charges with no payers_information at all (cash-only rows) still deliver normally, and a hospital whose payer key is intact is unaffected on every path (a row-cap stop on a healthy file still reports a cap-only PARTIAL with no CTA).
• v0.1.2: Red Team fix round. Nested and value-level drift no longer ships silently: a renamed payer_name key inside payers_information (JSON) or a renamed payer_name column (tall CSV) fails that hospital as structure drift at any file size; rows with an empty or missing procedure description are counted as invalid rows under the existing 20 percent machinery; non-empty price values that cannot be parsed as a number (dollar, gross, cash, min, max) are counted per hospital and reported as a source-caused PARTIAL with the count and first reason named (legitimately absent rates still ship as null, silently); care-setting values outside inpatient / outpatient / both are counted as drift instead of passing through or being silently filtered out. The Output section now discloses that percentage-based negotiated charges ship with negotiatedDollarRateUsd null and the percentage value is not emitted, and that the CMS v3.0 allowed-amount elements are not surfaced. CMS template v3.0 support is named explicitly (v3.0.0 files verified live). University Hospitals is described as 14 locations covering 13 unique files. When exact-duplicate rows are dropped by de-duplication, the per-source status line now states the duplicate count, so a matched count above the delivered count is explained.
• v0.1.1: Review fixes. Default hospital is University Hospitals only (the Mount Sinai default removed in spec cross-check is gone from the schema, code and examples). Scan budget default is now the 30 minute per-hospital cap, and hitting the scan budget or a row cap reports a per-hospital PARTIAL instead of Complete. Zero matches on a healthy scanned file is a successful Complete with 0 rows. Renamed code_information or standard_charges structures, empty charge arrays and header-only CSVs now fail that hospital loudly as structure drift. Rows scanned are reported per hospital. Fetches retry 6 times with jittered backoff and Retry-After honored. Default run options set: 1024 MB memory, $50 max total charge, 7200 s timeout.
• v0.1: Initial release. cms-hpt.txt resolution, streaming JSON / JSON.gz / tall and wide CSV / ZIP parsing, code-type-aware matching, per-hospital header validation and status reporting.