prove_hospital_price

What it answers

1. 1One hospital, one code, the rate by payer and plan name with a receipt (where negotiated rates by insurer live today; the insurer-file / TiC tools are coming soon).
2. 2Execute a bounded hospital chargemaster price proof and return rate summary values plus a receipt with source snapshot, filters, raw byte provenance, caveats, input hash, response hash, and replay pointer.

Inputs (11)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
prove_hospital_price(hospital_ccn="070005", billing_code="70450", max_rows=60)

curl -X POST https://api.vladahealth.com/v1/tools/prove_hospital_price \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hospital_ccn":"070005","billing_code":"70450","max_rows":60}'

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

A real answer

{
 "value": {
  "proof_kind": "hospital_price_proof",
  "source_table": "fact_hospital_chargemaster",
  "hospital_ccn": "070005",
  "billing_code": "70450",
  "version_id": null,
  "planned_file_count": 1,
  "planned_bytes": 93233000,
  "planned_record_count": 1908186,
  "planned_delete_file_count": 0,
  "plan_manifest_hash": "432b007b75d09646abed67f2ed3107945c3e9902b0518a03d1cffbceaa5b8abb",
  "row_count": 52,
  "status": "ok",
  "all_rows_have_byte_provenance": true,
  "distinct_payer_names": [
   "Aetna",
   "Anthem",
   "Anthem Pathway",
   "Cigna",
   "ConnectiCare",
   "DE-IDENTIFIED",
   "Evernorth Behavioral Health",
   "HOSPITAL",
   "United Behavioral Health",
   "United Healthcare"
  ],
  "distinct_plan_names": [
   "Aggregate Min/Max",
   "Cash Pay",
   "Commercial",
   "Gross Charge",
   "Medicare"
  ],
  "distinct_billing_classes": [
   "facility"
  ],
  "distinct_methodologies": [
   "",
   "case rate",
   "fee schedule",
   "other",
   "percent of total billed charges"
  ],
  "distinct_content_sha256": [
   "9a33aa0b5c67cc2a3c5cee0115ffa2bcf15f6ad5dd0dc69044111bdfdc1064fc"
  ],
  "distinct_raw_s3_keys": [
   "raw_archive/hospital/ccn=070005/9a33aa0b5c67cc2a3c5cee0115ffa2bcf15f6ad5dd0dc69044111bdfdc1064fc.csv"
  ],
  "distinct_mrf_version_ids": [
   "d9385d8c-2051-4955-9ae4-ff855c3ce334"
  ],
  "rate_count": 7,
  "min_rate": 44.03,
  "median_rate": 192.38,
  "p10_rate": 44.03,
  "p90_rate": 357.7,
  "max_rate": 357.7,
  "rate_basis": "fee_schedule",
  "rate_basis_natural_family": "fee_schedule",
  "rate_basis_rule": "min/p10/median/p90/max are over ONE payment basis: the code's natural family (fee_schedule) when posted, else a negotiated dollar with no stated methodology, else the other line/admission family. Gross charge, cash, percent-of-charge, per-diem and non-dollar forms are never pooled into it; each is in rates_by_basis.",
  "rates_by_basis": {
   "case_rate": {
    "row_count": 4,
    "seated": false,
    "rate_count": 4,
    "min_rate": 466.0,
    "median_rate": 524.5,
    "p10_rate": 466.0,
    "p90_rate": 583.0,
    "max_rate": 583.0
   },
   "cash": {
    "row_count": 4,
    "seated": false,
    "rate_count": 4,
    "min_rate": 958.85,
    "median_rate": 958.85,
    "p10_rate": 958.85,
    "p90_rate": 958.85,
    "max_rate": 958.85
   },
   "fee_schedule": {
    "row_count": 7,
    "seated": true,
    "rate_count": 7,
    "min_rate": 44.03,
    "median_rate": 192.38,
    "p10_rate": 44.03,
    "p90_rate": 357.7,
    "max_rate": 357.7
   },
   "gross_charge": {
    "row_count": 4,
    "seated": false,
    "rate_count": 4,
    "min_rate": 1917.69,
    "median_rate": 1917.69,
    "p10_rate": 1917.69,
    "p90_rate": 1917.69,
    "max_rate": 1917.69
   },
   "negotiated_methodology_unstated": {
    "row_count": 1,
    "seated": false,
    "rate_count": 1,
    "min_rate": 44.03,
    "median_rate": 44.03,
    "p10_rate": 44.03,
    "p90_rate": 44.03,
    "max_rate": 44.03
   },
   "non_dollar_form": {
    "row_count": 28,
    "seated": false,
    "rate_count": 0,
    "min_rate": null,
    "median_rate": null,
    "p10_rate": null,
    "p90_rate": null,
    "max_rate": null
   },
   "percent_of_charge": {
    "row_count": 4,
    "seated": false,
    "rate_count": 4,
    "min_rate": 660.84,
    "median_rate": 809.845,
    "p10_rate": 660.84,
    "p90_rate": 958.85,
    "max_rate": 958.85
   }
  },
  "all_rows_rate_count": 24,
  "rates_outside_basis_count": 17,
  "rate_basis_settings": {
   "outpatient": 7
  },
  "rate_basis_billing_classes": {
   "facility": 7
  },
  "summary_source": "fact_hospital_chargemaster",
  "verdict": "ok"
 },
 "unit": "USD",
 "vintage": null,
 "methodology": null,
 "caveats": [],
 "response_hash": "52caf8290716e14507686956574934dc7f25ba8404cb5784cf1caaddab47d113",
 "semantic_version": 1,
 "tool_version": "prove_hospital_price@1.5.0",
 "explanation": null,
 "status": "complete",
 "proof_id": "hospitalprice_19f06a3112497ebd",
 "receipt": {
  "receipt_version": "hospital_price_proof_receipt.v0",
  "substrate": "hospital",
  "proof_kind": "hospital_price_proof",
  "proof_id": "hospitalprice_19f06a3112497ebd",
  "tool_name": "prove_hospital_price",
  "tool_version": "1.5.0",
  "source_table": "fact_hospital_chargemaster",
  "source_descriptor": {
   "table": "fact_hospital_chargemaster",
   "snapshot_id": "4789942790573672775",
   "raw_s3_keys": [
    "raw_archive/hospital/ccn=070005/9a33aa0b5c67cc2a3c5cee0115ffa2bcf15f6ad5dd0dc69044111bdfdc1064fc.csv"
   ],
   "content_sha256": [
    "9a33aa0b5c67cc2a3c5cee0115ffa2bcf15f6ad5dd0dc69044111bdfdc1064fc"
   ],
   "mrf_version_ids": [
    "d9385d8c-2051-4955-9ae4-ff855c3ce334"
   ],
   "source_urls": [
    "https://vlada-platform-raw.s3.amazonaws.com/raw_archive/hospital/ccn%3D070005/9a33aa0b5c67cc2a3c5cee0115ffa2bcf15f6ad5dd0dc69044111bdfdc1064fc.csv"
   ],
   "parser_artifact_hashes": [
    "78df2514944e674eabf04d07f17a93ea1ab6255c6fff2bd4b3ec79d314e4a2b9"
   ],
   "s3_version_ids": []
  },
  "read_snapshot_set": {
   "fact_hospital_chargemaster": "4789942790573672775"
  },
  "filters": {
   "hospital_ccn": "070005",
   "billing_code": "70450",
   "current_only": true
  },
  "guardrails": {
   "max_rows": 60,
   "max_planned_files": 500,
   "max_planned_bytes": 268435456,
   "current_only": true,
   "require_byte_provenance": true,
   "raw_parquet_glob_reads": "disabled",
   "shared_mrf_expansion": "not_performed_mvp"
  },
  "plan": {
   "planned_file_count": 1,
   "planned_bytes": 93233000,
   "planned_record_count": 1908186,
   "planned_delete_file_count": 0,
   "plan_manifest_hash": "432b007b75d09646abed67f2ed3107945c3e9902b0518a03d1cffbceaa5b8abb",
   "planned_files_sample": [
    "data/_VXeSg/hospital_state=CT/hospital_ccn=070005/20261002_010134_00448_k6qzf-35fcae15-3a2d-46e0-8d5d-644da8afbb0b.parquet"
   ]
  },
  "evidence": {
   "plan": {
    "planned_file_count": 1,
    "planned_bytes": 93233000,
    "planned_record_count": 1908186,
    "planned_delete_file_count": 0,
    "plan_manifest_hash
…

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"
  }
 },
 "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": "ok",
   "enum": [
    "planned",
    "ok",
    "no_match",
    "rejected_guardrail",
    "too_large_for_sync",
    "summary_from_cell_table"
   ],
   "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"
  },
  "proof_id": {
   "default": "",
   "title": "Proof Id",
   "type": "string"
  },
  "receipt": {
   "additionalProperties": true,
   "title": "Receipt",
   "type": "object"
  }
 },
 "title": "HospitalPriceProofResponse",
 "type": "object"
}

Sources

Known limits (0)