get_stars_cutpoints

What it answers

1. 1Returns CMS-published per-measure star-level cut points (the threshold a contract must reach for stars 2 to 5) for a rating_year, read through the Stars measure spine so a measure keeps its identity across years even when CMS renumbers its code (27 of 33 Part C codes moved for RY2026).
2. 2TWO SHAPES.
3. 3Pass measure_id (that year's code, e.g.
4. 4C09; a trailing ':' as stored is accepted) or measure_identity_key (the stable key, e.g. 'c:controlling_blood_pressure') for ONE measure: value.measure carries the identity, the star_2 to star_5 thresholds with their ops, the prior and next year's code and the ladder direction; value.cutpoints carries the raw CMS rows; include_history=true adds value.history, the same identity's ladder in every rated year (cut point drift).
5. 5With neither, value.measures is a paged index of the year's measures (limit, offset; default 50 rows) and the answer names the per-measure call.
6. 6LADDER.
7. 7CMS calculates MA-PD and PDP Part D cut points separately.
8. 8The header (value.measure and the index rows) reads the ladder for org_subtype: MA-PD by default (the Medicare Advantage question), PDP for a stand-alone drug plan question; cutpoint_org_subtype names the ladder read, and it is ALL only where CMS published one ladder for every organisation (Part C). org_subtype (MA-PD | PDP | ALL) and star_level (1-5) also filter the raw rows.
9. 9Use cases: 'what is the 4-star line for Controlling Blood Pressure in RY2027?'; 'how did that line move since RY2024?'; 'how much would contract H1234 need to improve to reach 5 stars on D08?'.
10. 10SOURCE: CMS Tech Notes Attachment H (Tukey-aware threshold tables) for RY2024+, Attachment H pre-Tukey for RY2017-RY2023, pre-fixed cut points for RY2015-RY2016.
11. 11RY2027 is CMS's final release (the 2027 Data Tables, 2026-10-08); the plan-preview rows it replaced stay readable as superseded (is_current = false).
12. 12Spine: medicare_semantic.dim_stars_measure_identity_v7 (tools/ma_brain/stars_measure_spine_publish.py), whose direction flag agrees with CMS's own cut point ladder in every rated year.
13. 13FLOOR BANDS.
14. 14Where CMS printed NA for the lowest star bands (some measures in RY2015 and RY2018-2021), the band's op is 'floor' and its threshold is null: every score reaches it. floor_star names the lowest band CMS printed (3 stars on every MA floor ladder, e.g.
15. 15RY2019 Kidney Disease Monitoring: no 1- or 2-star band, 3 stars at 87% or more;
16. 16RY2020 Complaints about the Health Plan: 3 stars above 1.29).
17. 17HOLDINGS ARE NAMED, NEVER IMPLIED.
18. 18When a rating year holds only ONE Part D ladder the answer says so and which population it is for.
19. 19A measure with no cut point rows in a year is reported as not held in this edition, with the years held named;
20. 20CMS publishes cut points every year.
21. 21Thresholds are served at the precision CMS publishes (float32 storage noise is removed on the wire).

Inputs (8)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
get_stars_cutpoints(rating_year=2026, measure_id="C14", include_history=true)

curl -X POST https://api.vladahealth.com/v1/tools/get_stars_cutpoints \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating_year":2026,"measure_id":"C14","include_history":true}'

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

A real answer

{
 "value": {
  "found": true,
  "rating_year": 2026,
  "shape": "measure",
  "measure": {
   "measure_id": "C14",
   "measure_identity_key": "c:controlling_blood_pressure",
   "canonical_name": "Controlling Blood Pressure",
   "part": "C",
   "domain": "HD2",
   "weight": 3.0,
   "direction": "higher",
   "direction_latest": "higher",
   "ladder_direction": "ascending",
   "prior_year_measure_id": "C11",
   "next_year_measure_id": "C14",
   "code_moved": true,
   "is_new_this_year": false,
   "is_retired": false,
   "cmit_number": "00167-02-C-PARTC",
   "has_cutpoints": true,
   "cutpoint_org_subtype": "ALL",
   "thresholds": {
    "star_2": {
     "threshold": 67.0,
     "op": ">="
    },
    "star_3": {
     "threshold": 75.0,
     "op": ">="
    },
    "star_4": {
     "threshold": 80.0,
     "op": ">="
    },
    "star_5": {
     "threshold": 86.0,
     "op": ">="
    }
   },
   "ladders_held": [
    "ALL"
   ]
  },
  "cutpoints": [
   {
    "measure_id": "C14",
    "star_level": 1,
    "org_subtype": "ALL",
    "threshold_lower_bound": null,
    "threshold_upper_bound": 67.0,
    "threshold_lower_op": null,
    "threshold_upper_op": "<",
    "raw_threshold_text": "< 67 %"
   },
   {
    "measure_id": "C14",
    "star_level": 2,
    "org_subtype": "ALL",
    "threshold_lower_bound": 67.0,
    "threshold_upper_bound": 75.0,
    "threshold_lower_op": ">=",
    "threshold_upper_op": "<",
    "raw_threshold_text": ">= 67 % to < 75 %"
   },
   {
    "measure_id": "C14",
    "star_level": 3,
    "org_subtype": "ALL",
    "threshold_lower_bound": 75.0,
    "threshold_upper_bound": 80.0,
    "threshold_lower_op": ">=",
    "threshold_upper_op": "<",
    "raw_threshold_text": ">= 75 % to < 80 %"
   },
   {
    "measure_id": "C14",
    "star_level": 4,
    "org_subtype": "ALL",
    "threshold_lower_bound": 80.0,
    "threshold_upper_bound": 86.0,
    "threshold_lower_op": ">=",
    "threshold_upper_op": "<",
    "raw_threshold_text": ">= 80 % to < 86 %"
   },
   {
    "measure_id": "C14",
    "star_level": 5,
    "org_subtype": "ALL",
    "threshold_lower_bound": 86.0,
    "threshold_upper_bound": null,
    "threshold_lower_op": ">=",
    "threshold_upper_op": null,
    "raw_threshold_text": ">= 86 %"
   }
  ],
  "total_cutpoints_returned": 5,
  "history": [
   {
    "rating_year": 2015,
    "measure_id": "C18",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 42.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 53.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 63.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 75.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2016,
    "measure_id": "C16",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 47.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 62.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 75.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 82.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2017,
    "measure_id": "C16",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 38.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 56.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 64.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 75.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2018,
    "measure_id": "C16",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 55.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 67.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 75.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 86.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2019,
    "measure_id": "C16",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 51.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 62.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 75.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 82.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2023,
    "measure_id": "C12",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 48.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 63.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 73.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 80.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2024,
    "measure_id": "C11",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 58.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 68.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 74.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 82.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2025,
    "measure_id": "C11",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 69.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 74.0,
      "op": ">="
     },
     "star_4": {
      "threshold": 80.0,
      "op": ">="
     },
     "star_5": {
      "threshold": 85.0,
      "op": ">="
     }
    }
   },
   {
    "rating_year": 2026,
    "measure_id": "C14",
    "ladder_direction": "ascending",
    "cutpoint_org_subtype": "ALL",
    "thresholds": {
     "star_2": {
      "threshold": 67.0,
      "op": ">="
     },
     "star_3": {
      "threshold": 75.0,
      "op": ">="
     },
     "star_4": {

…

What comes back

Sources

Known limits (1)

1. 1stars_methodology_pdf_uncited