# medicare_allowed

Medicare Allowed · v0.1.0 · medicare

Returns the Medicare allowed amount for ONE billing code (CPT/HCPCS, or an MS-DRG for inpatient) from every Medicare fee schedule that prices it: PFS (professional, national non-facility), OPPS Addendum B (hospital outpatient APC), ASC, CLFS (lab), and IPPS (national DRG amount). Inputs: billing_code (required); optional care_class to pick the setting that fits a site (02_asc, 03_outpatient, 04_urgent_care, 05_imaging, 06_lab, 07_dialysis — the same preference table the care-site price bridge uses for its Medicare floor); optional setting to return one schedule only (PFS_non_facility | OPPS_APC | ASC | CLFS | IPPS_MSDRG_national); optional medicare_year to PIN a schedule vintage (4-digit year; omit it and the LATEST edition held for the chosen schedule is served — an older vintage is never returned unless you pin it); optional limit.

RETURNS a detail payload: value.medicare_year and value.setting state the vintage and schedule actually served; value.summary carries the PREFERRED row for the requested care_class (medicare_allowed, medicare_source, medicare_year, billing_class), the latest year held per schedule (latest_year_by_schedule) and whether the year was pinned or resolved (medicare_year_selection), plus the count of schedules that price the code; value.settings lists EVERY schedule row for the code with what it is (fee_schedule, professional vs facility component, site, national basis, locality_adjusted=false, source_table, medicare_year vintage). Every number is NATIONAL — no GPCI / wage-index localisation is applied, and PFS is the NON-FACILITY (office) professional rate. A code priced on no schedule returns found=false ('not priced on these Medicare schedules', never $0). Reads the latest available edition per schedule (vlada_curated.vw_medicare_benchmark_effective per schedule, so an ASC rate is listed beside the OPPS rate for the same code; the underlying M-2 fact tables are read WHERE is_current).

SOURCE: CMS PFS RVU + conversion factor, OPPS Addendum B, ASC addendum, CLFS, IPPS Table 5 + base rates.

**Inputs.**
- `billing_code` (required): 
- `care_class`: 
- `setting`: 
- `medicare_year`: 
- `limit`: 

**Known limits.**
- National amounts only: no GPCI (PFS) or wage-index (OPPS/ASC/IPPS) localisation.
- PFS is the non-facility (office) professional rate; the facility-setting professional rate is not served.
- DMEPOS / anesthesia / ESRD schedules are not loaded; a code absent from every served schedule is 'not priced here', not $0.

**A real answer** (customer seat, 0.09 s, args `{"billing_code":"70450","medicare_year":2026}`):

```json
{
 "value": {
  "found": true,
  "not_found_reason": null,
  "summary": {
   "billing_code": "70450",
   "medicare_allowed": 106.81,
   "unit": "USD",
   "medicare_source": "OPPS_APC",
   "fee_schedule": "OPPS",
   "component": "facility",
   "site": "hospital_outpatient",
   "billing_class": "institutional",
   "medicare_year": 2026,
   "basis": "national",
   "locality_adjusted": false,
   "preferred_by": "default_setting_order",
   "schedules_pricing_code": [
    "ASC",
    "OPPS_APC",
    "PFS_non_facility"
   ],
   "schedule_count": 3,
   "latest_year_by_schedule": {
    "ASC": 2026,
    "OPPS_APC": 2026,
    "PFS_non_facility": 2026
   },
   "medicare_year_selection": "pinned_by_caller"
  },
  "settings": [
   {
    "billing_code": "70450",
    "medicare_source": "ASC",
    "billing_class": "institutional",
    "medicare_allowed": 57.04,
    "unit": "USD",
    "medicare_year": 2026,
    "fee_schedule": "ASC",
    "component": "facility",
    "site": "ambulatory_surgical_center",
    "basis": "national",
    "locality_adjusted": false,
    "note": "ASC addendum payment_rate, national (no wage index)."
   },
   {
    "billing_code": "70450",
    "medicare_source": "OPPS_APC",
    "billing_class": "institutional",
    "medicare_allowed": 106.81,
    "unit": "USD",
    "medicare_year": 2026,
    "fee_schedule": "OPPS",
    "component": "facility",
    "site": "hospital_outpatient",
    "basis": "national",
    "locality_adjusted": false,
    "note": "Addendum B APC payment_rate, national (no wage index). Do NOT benchmark a facility charge against PFS."
   },
   {
    "billing_code": "70450",
    "medicare_source": "PFS_non_facility",
    "billing_class": "professional",
    "medicare_allowed": 106.55,
    "unit": "USD",
    "medicare_year": 2026,
    "fee_schedule": "PFS",
    "component": "professional",
    "site": "non_facility",
    "basis": "national",
    "locality_adjusted": false,
    "note": "total_non_facility_rvu x conversion factor, modifier '' (global), default payment track; NOT GPCI/locality-adjusted; the FACILITY professional rate is lower and is not returned here."
   }
  ],
  "row_counts": {
   "settings": {
    "matched": 3,
    "returned": 3,
    "truncated": false,
    "limit": 200,
    "kept": "head"
   }
  },
  "query": {
   "billing_code": "70450",
   "care_class": null,
   "setting": null,
   "medicare_year": 2026,
   "limit": 200
  },
  "query_id": "fe3964e7-ddce-4c17-ba5b-603ef49b65ce",
  "medicare_year": 2026,
  "setting": "OPPS_APC"
 },
 "unit": "medicare_allowed_detail",
 "result_status": "answered",
 "methodology_era": null,
 "methodology_blend_factors": null,
 "source": {
  "source_url": "medicare://medicare_allowed"
 },
 "vintage": "as_restated",
 "cms_vintage_sequence": 1,
 "parse_revision": 1,
 "as_of_observed": null,
 "as_of_asserted": null,
 "as_of_effective": null,
 "caveats": [],
 "confidence": null,
 "finality_confidence": null,
 "response_hash": "4f141a99ed4dd3d76bac6700a99f8babd2280d0169a7bfe8e03f40c75745a498",
 "semantic_version": 1,
 "tool_version": "0.1.0",
 "parser_artifact_hash": "0b11193fb97519397f53ffe2917938b1bf95f408fccb5bae6d356b17ef22a148",
 "parser_artifact_hash_basis": "tool_source_sha256",
 "signature": null,
 "tenant_id": "probe-customer-canary",
 "status": "complete",
 "audit_id": "837a66a3-1467-4665-a310-6d8a580181ef",
 "timestamp": "2026-11-09T21:29:02.787809Z",
 "request_id": "bb41e214-bd02-4cea-a098-59d94aa51e65",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "medicare_allowed_detail",
  "scope": {
   "tool": "medicare_allowed",
   "filters": {
    "billing_code": "70450",
    "medicare_year": 2026
   }
  }
 },
 "method": "Read from the CMS publication. The published values are reported as published, with no adjustment or modelling applied.",
 "evidence": {
  "query_id": "fe3964e7-ddce-4c17-ba5b-603ef49b65ce",
  "response_hash": "4f141a99ed4dd3d76bac6700a99f8babd2280d0169a7bfe8e03f40c75745a498",
  "audit_id": "837a66a3-1467-4665-a310-6d8a580181ef",
  "request_id": "bb41e214-bd02-4cea-a098-59d94aa51e65"
 }
}
```

REST: `POST https://api.vladahealth.com/v1/tools/medicare_allowed` with the inputs as the JSON body. MCP: the tool by name.