compare_hospital_rates

What it answers

1. 1NEGOTIATED RATES BY INSURER AND PLAN ARE SERVED HERE: hospital price-transparency files carry the rate each hospital filed for each payer and plan (the insurer-file / TiC tools are coming soon).
2. 2Compares what a billing code costs ACROSS hospitals (cheapest real price first) with a p10/median/p90 benchmark AND a per-(payer x line-of-business) breakdown.
3. 3The product query for 'where is care cheapest' and 'what does each payer actually pay'.
4. 4Reads the canonical serving view `vlada_curated.vw_fact_hospital_chargemaster_canonical`, which resolves each raw payer string to its REAL parent entity (the canonical payer graph) and classifies each plan to a regulatory line-of-business (commercial / medicare_advantage / medicaid / marketplace / ...).
5. 5Inputs: billing_code (required), state (optional 2-letter), code_system (optional), billing_class (default 'institutional' = facility/UB-04; or 'professional'/'both'; classes are never mixed -- since 1.6.0 'institutional'/'professional' each WIDEN to include billing_class_resolved='both' rows, a charge posted on both the facility and professional side of a bill per the HPT schema; pass 'institutional_only'/'professional_only' for the strict single-class stratum), limit (default 25), payer (optional brand OR parent, e.g. 'Aetna' or 'CVS Health'), line_of_business (optional, e.g. 'medicare_advantage';
6. 6`all_products` is one rate a hospital posts for all of a payer's products, and it is never in the commercial default).
7. 7Each returned rate carries the view's canonical payer columns (`payer_canonical_id`, `payer_parent_name`, `payer_entity_class`, `payer_match_method`) plus `line_of_business` so a comparison is apples-to-apples (Aetna-MA != Aetna-Commercial).
8. 8`value.by_payer_lob` is the 'rates across all the payers' table.
9. 9CROSS-SUBSTRATE: every rate also carries x_medicare (the multiple of the Medicare allowed amount: PFS national non-facility for professional, OPPS APC for outpatient institutional, IPPS MS-DRG national base for inpatient DRG codes);
10. 10`value.medicare` holds the allowed amount + schedule + year, so the answer is 'this payer pays 1.6x Medicare at this hospital'.
11. 11VALIDATION (load-bearing): billing_class is normalized + inferred from code_system/rate_type where the source omits it; only the requested class is compared; class-implausible rates (e.g. $0.007 for a CT) and code-relative outliers are filtered.
12. 12CHEAPEST HEADLINE (1.2.0): `value.cheapest` is ranked over rows PLAUSIBLE for the code's Medicare basis -- when the allowed amount is a real procedure (>= $500) a row under 0.3x Medicare (the comparability cascade's own lower sane bound) is set aside into `value.implausible_tail` (full rows + floor + reason, never deleted; benchmark still includes it), and the rest rank hospital-stated methodology (fee_schedule/case_rate/per_diem) before methodology-unknown, rate ascending within each tier -- read `plausibility` + `rank_tier` on each row.
13. 13Under the $500 gate (imaging / visits / labs) only the placeholder floor below applies, so a $44 head CT still headlines.
14. 14CASE-RATE HEADLINE (1.7.0): on a DRG/case-rate seat the floor is 0.5x (not 0.3x -- an inpatient rate below half of IPPS is not credible as the full case price), and `cheapest` headlines hospital-STATED case_rate rows ONLY when at least one survives the floor; methodology-unknown rows are demoted into `value.implausible_tail` (tail_reason='methodology_unknown_demoted') even when they themselves clear the floor.
15. 15`cheapest` headlines an unknown row only when NO stated row survives, and a `headline_methodology_unknown` warning caveat says so.
16. 16ENCOUNTER-BASIS FLOOR (1.15.0): the floor also reads the Medicare basis -- when the allowed amount is a facility-encounter payment (OPPS APC, IPPS MS-DRG, ASC; e.g. the comprehensive APC behind a CPT 27447 knee) the floor is 0.5x on every seat except per_diem, stated as `floor_rule='encounter_basis'` on every floor block and on value.implausible_tail.
17. 17ONE CODE SYSTEM PER WINDOW (1.3.0): `cheapest` holds rows of the seated code system only (`value.code_system_resolved`, the dominant system or the caller's `code_system`), each row stamped `code_system`; when the floor empties a full window the tool re-asks once for rows at or above the floor rate (`value.cheapest_window.second_pass`), and if `cheapest` still ends empty a `no_plausible_rows_in_window` caveat says why.
18. 18ONE METHODOLOGY FAMILY PER WINDOW (1.4.0): within the seated code system, `cheapest` and the re-seated `value.benchmark` / `comparable_benchmark` are further restricted to ONE methodology family -- fee_schedule (a line, the natural family for CPT/HCPCS/APC/RC), case_rate (an admission, the natural family for a DRG/MS-DRG seat), or per_diem (a day) -- because a case rate, a per diem and a fee schedule price different economic objects and must never share a median or a ranked list.
19. 19`methodology_family` (optional: fee_schedule|case_rate|per_diem) overrides the natural seat.
20. 20Rows the hospital stated in a DIFFERENT family are set aside into `value.other_family`, in full, never blended in;
21. 21`value.by_methodology_family` reports n/n_hospitals/p10/median/p90 for every family present, and a `methodology_families_mixed` caveat fires when more than 10% of the population sits outside the seated family.
22. 22BY_METHODOLOGY RECONCILES (1.6.1): `value.by_methodology` (percent_of_charge/fee_schedule/case_rate/per_diem/other/unknown, with median_rate_over_gross_charge) is narrowed to the SAME population `value.benchmark.n` reports -- sum(by_methodology[].n) == benchmark.n, ALWAYS, by construction; the unstratified, every-family view (within the seated code system) is `value.by_methodology_all_families`, which is what `value.percent_of_charge_share` and the `methodology_mix` caveat read (percent_of_charge rows are always 'unknown' family and would otherwise be invisible once a family is seated).
23. 23SOURCE: CMS Hospital Price Transparency MRFs (45 CFR 180.50) + CMS Medicare PFS/OPPS fee schedules.
24. 24KNOWN GAPS: not geo-aware beyond state; payer resolution covers ~80.9% of volume and line-of-business ~85.7% (measured on the 70553 probe, 2026-08-13; call state_expert for live per-state counts), unmatched rates fall to '(unresolved)'/'unspecified'; bare Blue-family labels (e.g. 'Bcbs') keep the Blue company the hospital's state or county identifies (the state's one licensee, or the county's Blue in a split state); with no such evidence they are bucketed '(blue family: label too generic to attribute)' with payer_resolution='generic_label' and never attributed to a specific Blue parent;
25. 25IPPS DRG x_medicare is the national base (excludes wage index/IME/DSH/outliers); x_medicare null for revenue/non-HCPCS CDM codes; ghost-rate filter is heuristic.
26. 26DRG GROUPER PRECISION: MS-DRG, APR-DRG and AP-DRG are different maintainers with different numbering (MS-DRG 470 = joint replacement, APR-DRG 470 = chronic kidney disease) and only MS-DRG prices against the IPPS base.
27. 27Served data is split into MS_DRG / APR_DRG / TRIS_DRG / ...
28. 28(code_system_precision 'token' or 'shape_inferred'), so an MS_DRG seat is `value.medicare.precision` 'exact' and the other groupers carry no Medicare basis; only a row still on the transitional bare 'DRG' string reads 'drg_grouper_unknown'.
29. 29CODE-SYSTEM SPELLINGS (1.18.0): code_system is folded to the served bucket before anything runs ('MS-DRG' / 'ms_drg' / 'msdrg' -> 'MS_DRG', 'APR-DRG' -> 'APR_DRG', 'hcpcs' -> 'HCPCS_II', 'cpt-4' -> 'CPT'; a bare 'DRG' is not guessed), and code_system naming the cell's natural seat is served from the precomputed table.
30. 30PAYER FROM THE TABLE (1.18.0): payer naming ONE parent company (the parent name, or a brand it owns: Aetna -> CVS Health, UHC -> UnitedHealth Group, Anthem -> Elevance Health) is read from the table's payer level -- the headline is that parent's seated-family rows; value.served_from.payer_scope names the match; by_methodology and comparable_benchmark are not in the table per payer and say so in value.sections_unavailable.
31. 31`by_payer_lob` lists the seated methodology family first;
32. 32`value.by_payer_lob_cut` and each tail's `rows_cut_note` say where a list was cut.
33. 33PLACEHOLDER TAIL (1.18.0; from a $100 basis since 1.20.0): under the $500 gate, a rate under 0.25x a $100-$500 Medicare basis (a $50 ED visit at 0.12x, a $32 brain MRI at 0.13x) leaves the ranked `cheapest` list for value.implausible_tail (tail_reason='below_low_basis_floor'); the medians still include it until the table is rebuilt.
34. 34NO HEADLINE WITHOUT ITS FLOOR (1.22.0): when the seat or the Medicare part misses the budget, `cheapest` is withheld (value.cheapest_empty rule 'seat_unavailable', status partial, retryable) and the window's rows are in value.cheapest_unassessed, unranked.
35. 35BOTH-CLASS DEFAULT STRATUM (1.6.0): billing_class 'institutional'/'professional' each widen to include billing_class_resolved='both' rows (a charge the HPT schema posts for both sides of a bill); every row still carries its own resolved `billing_class`, and a `both_class_rows_included` caveat states the measured count whenever the answer includes at least one such row.
36. 36Measured on CT (2026-08-18): 9.63% of REAL_NEGOTIATED rows are 'both', 100% with no institutional sibling row -- previously invisible at the old strict-institutional default.
37. 37Pass 'institutional_only'/'professional_only' for the pre-1.6.0 strict single-class stratum.

Inputs (11)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
compare_hospital_rates(billing_code="70450", state="CT", line_of_business="commercial", limit=3)

curl -X POST https://api.vladahealth.com/v1/tools/compare_hospital_rates \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"billing_code":"70450","state":"CT","line_of_business":"commercial","limit":3}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/compare_hospital_rates/schema

A real answer

{
 "value": {
  "cheapest": [
   {
    "hospital_ccn": "070005",
    "hospital_name": "WATERBURY HOSPITAL",
    "hospital_state": "CT",
    "payer_name": "Aetna",
    "payer_parent_name": "CVS Health",
    "payer_resolution": "resolved",
    "payer_parents_sharing_price": 1,
    "payer_labels_sharing_price": 1,
    "payer_entity_class": null,
    "plan_name": "Commercial",
    "line_of_business": "commercial",
    "plan_product_structure": null,
    "billing_class": "institutional",
    "code_system": "CPT",
    "methodology": "fee_schedule",
    "methodology_family": "fee_schedule",
    "rate": 44.03,
    "gross_charge": null,
    "cash_price": null,
    "x_medicare": 0.41,
    "x_medicare_wage_adjusted": 0.35,
    "medicare_allowed_wage_adjusted": 125.33,
    "wage_index": 1.289,
    "wage_index_fiscal_year": 2026,
    "wage_adjustment_status": "wage_adjusted",
    "facility_type": "acute",
    "plausibility": "not_assessed",
    "rank_tier": "stated_methodology",
    "price_kind": "negotiated price",
    "price_basis": "hospital-stated fee schedule"
   },
   {
    "hospital_ccn": "070027",
    "hospital_name": "MANCHESTER MEMORIAL HOSPITAL",
    "hospital_state": "CT",
    "payer_name": "Aetna Whole Health",
    "payer_parent_name": "CVS Health",
    "payer_resolution": "resolved",
    "payer_parents_sharing_price": 1,
    "payer_labels_sharing_price": 1,
    "payer_entity_class": null,
    "plan_name": "Commercial",
    "line_of_business": "commercial",
    "plan_product_structure": null,
    "billing_class": "institutional",
    "code_system": "CPT",
    "methodology": "fee_schedule",
    "methodology_family": "fee_schedule",
    "rate": 61.71,
    "gross_charge": null,
    "cash_price": null,
    "x_medicare": 0.58,
    "x_medicare_wage_adjusted": 0.49,
    "medicare_allowed_wage_adjusted": 125.33,
    "wage_index": 1.289,
    "wage_index_fiscal_year": 2026,
    "wage_adjustment_status": "wage_adjusted",
    "facility_type": "acute",
    "plausibility": "not_assessed",
    "rank_tier": "stated_methodology",
    "price_kind": "negotiated price",
    "price_basis": "hospital-stated fee schedule"
   },
   {
    "hospital_ccn": "070027",
    "hospital_name": "MANCHESTER MEMORIAL HOSPITAL",
    "hospital_state": "CT",
    "payer_name": "Aetna",
    "payer_parent_name": "CVS Health",
    "payer_resolution": "resolved",
    "payer_parents_sharing_price": 1,
    "payer_labels_sharing_price": 1,
    "payer_entity_class": null,
    "plan_name": "Commercial",
    "line_of_business": "commercial",
    "plan_product_structure": null,
    "billing_class": "institutional",
    "code_system": "CPT",
    "methodology": "fee_schedule",
    "methodology_family": "fee_schedule",
    "rate": 64.29,
    "gross_charge": null,
    "cash_price": null,
    "x_medicare": 0.6,
    "x_medicare_wage_adjusted": 0.51,
    "medicare_allowed_wage_adjusted": 125.33,
    "wage_index": 1.289,
    "wage_index_fiscal_year": 2026,
    "wage_adjustment_status": "wage_adjusted",
    "facility_type": "acute",
    "plausibility": "not_assessed",
    "rank_tier": "stated_methodology",
    "price_kind": "negotiated price",
    "price_basis": "hospital-stated fee schedule"
   }
  ],
  "cheapest_count": 3,
  "cheapest_empty": null,
  "benchmark": {
   "n": 98,
   "n_below_floor": 0,
   "p10": 139.2,
   "median": 243.98,
   "p90": 450.95,
   "min": null,
   "max": null,
   "median_x_medicare": 2.28,
   "median_x_medicare_basis": "national_unadjusted",
   "code_system": "CPT",
   "code_system_basis": "sole",
   "min_max_withheld": "not computed per methodology family",
   "n_hospitals": 18,
   "blended_n_across_all_methodology_families": 121,
   "family_seated": "fee_schedule",
   "family_basis": "natural",
   "plausibility_floor": {
    "applied": false,
    "floor_x_medicare": 0.5,
    "floor_rate": null,
    "medicare_allowed": 106.81,
    "basis_min_usd": 500.0,
    "filters_this_section": false,
    "note": "plausibility_floor",
    "excluded_below_floor_n": 0,
    "n_after_floor": 98,
    "all_rows_below_floor": false,
    "below_floor": [],
    "floor_invariant_violated": false
   },
   "form_split": {
    "dollar_n": 98,
    "percent_form_n": 28,
    "algorithm_form_n": 28,
    "note": "dollar_n = benchmark.n (the median population; dollar-published negotiated rates only). percent_form_n / algorithm_form_n = negotiated rates this code+class+geo publishes as a percentage / an algorithm (rate is NULL; the payload is the percentage or formula text). Form rows are NEVER blended into any dollar median."
   },
   "comparison_grade": "A",
   "grade_reason": "same code system + single hospital-stated methodology family 'fee_schedule' (grain per_service, grain confidence 'stated' by construction of the family reseat), n=98"
  },
  "comparable_benchmark": {
   "stratum": "fee_schedule",
   "weighting": "ccn_weighted",
   "median": 296.49,
   "median_x_medicare": 2.78,
   "p10": 167.6,
   "p90": 451.91,
   "n_hospitals": 18,
   "n_below_floor": 0,
   "n_hospitals_fully_excluded": 0,
   "n": 18,
   "note": "the like-for-like comparable price: fee_schedule (negotiated-dollar, same economic object) rates only, excluding every other methodology family, and CCN-WEIGHTED (each hospital's own median, then the median across hospitals \u2014 one hospital can't dominate). Rows below this seat's plausibility floor are excluded before the per-hospital medians are taken, the same rule the rest of this answer applies. Quote THIS, not the blended benchmark.",
   "plausibility_floor": {
    "applied": false,
    "floor_x_medicare": 0.5,
    "floor_rate": null,
    "medicare_allowed": 106.81,
    "basis_min_usd": 500.0,
    "filters_this_section": false,
    "note": "plausibility_floor",
    "excluded_below_floor_n": 0,
    "n_after_floor": 18,
    "all_rows_below_floor": false,
    "below_floor": [],
    "floor_invariant_violated": false
   }
  },
  "by_payer_lob": [
   {
    "payer_parent_name": "Elevance Health",
    "line_of_business": "commercia
…

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "description": "Value carries {billing_code, state, billing_class, cheapest[], benchmark}.",
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "CompareHospitalRatesResponse",
 "type": "object"
}

Sources

Known limits (3)

1. 1hospital_billing_class_inferred
2. 2hospital_geo_state_only
3. 3hospital_ghost_rate_filter_heuristic