get_stars

What it answers

1. 1Returns a Medicare Advantage contract's CMS Star Ratings: the Overall, Part C, and Part D summary stars for a rating year, each with the year-over-year change vs the prior year.
2. 2Set include_measures=true to also get the full per-measure breakdown (measure name, identity key, part, domain, weight, direction, the raw value and its star, the 4-star line, and the star's YoY change) so you can see exactly which measures moved the rating.
3. 3The prior-year star is matched by MEASURE IDENTITY through the Stars measure spine, never by code (CMS renumbered 27 of 33 Part C codes for RY2026); prior_year_measure_id names the code the prior star was filed under.
4. 4Filter by contract_id (required) + optional year (the rating_year, defaults to the latest) + optional limit (max measure rows returned).
5. 5Rating years 2012-2027 (RY2027 is CMS's final October 2026 release).
6. 6The answer is a detail payload: the headline stars sit in value.summary, the part rows in value.summary_parts, the measure rows in value.measures.
7. 7Stars drive the quality-bonus payment and rebate, so this sits directly upstream of the plan economics (payment and MLR) and is reported at the CONTRACT level (no plan_id).
8. 8Scores are served at the precision CMS publishes (float32 storage noise is removed on the wire).
9. 9Each measure row's four_star_ladder names the cut point ladder its four-star line came from: CMS calculates MA-PD and PDP Part D cut points separately, so an MA contract (H, R) reads the MA-PD ladder and a stand-alone drug plan contract (S) the PDP ladder;
10. 10ALL is a ladder CMS published for every organisation (Part C).
11. 11RESTATED OVERALL.
12. 12CMS restated 50 contracts' RY2026 Overall rating on July 22, 2026 (after the Clover Health ruling) without changing any measure star, so for those contracts the measure breakdown reflects the original calculation and can round to a different star than the served Overall.
13. 13The answer says so in a caveat and names the original value in summary.overall_restated_from (summary.overall_restated_from_text carries CMS's text when the original was a message such as 'Not enough data available').
14. 14FLOOR BANDS.
15. 15Where CMS printed NA for a measure's lowest star bands (some measures in RY2015 and RY2018-2021) the measure row names the lowest band CMS printed in floor_star and floor_note.
16. 16SOURCE: CMS Star Ratings (summary + measure-level) and the Vlada measure spine medicare_semantic.dim_stars_measure_identity_v7.

Inputs (4)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
get_stars(contract_id="H5216", year=2026, include_measures=true)

curl -X POST https://api.vladahealth.com/v1/tools/get_stars \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"H5216","year":2026,"include_measures":true}'

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

A real answer

{
 "value": {
  "found": true,
  "not_found_reason": null,
  "summary": {
   "contract_id": "H5216",
   "rating_year": 2026,
   "overall_star": 3.5,
   "overall_yoy_change": 0.0,
   "part_c_star": 3.5,
   "part_d_star": 3.0,
   "measure_count": 45,
   "measures_with_prior": 42,
   "measures_up": 12,
   "measures_down": 11,
   "include_measures": true,
   "overall_restated_from": null,
   "overall_restated_from_text": null,
   "unit": "stars_rows"
  },
  "summary_parts": [
   {
    "part": "Overall",
    "rating_year": 2026,
    "summary_star": 3.5,
    "prior_year_star": 3.5,
    "yoy_change": 0.0
   },
   {
    "part": "C",
    "rating_year": 2026,
    "summary_star": 3.5,
    "prior_year_star": 3.5,
    "yoy_change": 0.0
   },
   {
    "part": "D",
    "rating_year": 2026,
    "summary_star": 3.0,
    "prior_year_star": 3.5,
    "yoy_change": -0.5
   }
  ],
  "measures": [
   {
    "measure_id": "C01",
    "measure_identity_key": "c:breast_cancer_screening",
    "measure_name": "Breast Cancer Screening",
    "canonical_name": "Breast Cancer Screening",
    "cmit_number": "00093-02-C-PARTC",
    "part": "C",
    "domain": "HD1",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 4.0,
    "raw_value": 76.0,
    "four_star_line": 76.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": 4.0,
    "prior_year_measure_id": "C01",
    "yoy_change": 0.0
   },
   {
    "measure_id": "C02",
    "measure_identity_key": "c:colorectal_cancer_screening",
    "measure_name": "Colorectal Cancer Screening",
    "canonical_name": "Colorectal Cancer Screening",
    "cmit_number": "00139-02-C-PARTC",
    "part": "C",
    "domain": "HD1",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 4.0,
    "raw_value": 73.0,
    "four_star_line": 70.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": 4.0,
    "prior_year_measure_id": "C02",
    "yoy_change": 0.0
   },
   {
    "measure_id": "C03",
    "measure_identity_key": "c:annual_flu_vaccine",
    "measure_name": "Annual Flu Vaccine",
    "canonical_name": "Annual Flu Vaccine",
    "cmit_number": "00259-01-C-PARTC",
    "part": "C",
    "domain": "HD1",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 4.0,
    "raw_value": 68.0,
    "four_star_line": 68.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": 3.0,
    "prior_year_measure_id": "C03",
    "yoy_change": 1.0
   },
   {
    "measure_id": "C04",
    "measure_identity_key": "c:improving_or_maintaining_physical_health",
    "measure_name": "Improving or Maintaining Physical Health",
    "canonical_name": "Improving or Maintaining Physical Health",
    "cmit_number": null,
    "part": "C",
    "domain": "HD1",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 2.0,
    "raw_value": 68.0,
    "four_star_line": 72.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": null,
    "prior_year_measure_id": null,
    "yoy_change": null,
    "series_break": true,
    "series_break_kind": "new_measure",
    "series_break_note": "CMS changed this measure this year; last year's star is not comparable"
   },
   {
    "measure_id": "C05",
    "measure_identity_key": "c:improving_or_maintaining_mental_health",
    "measure_name": "Improving or Maintaining Mental Health",
    "canonical_name": "Improving or Maintaining Mental Health",
    "cmit_number": null,
    "part": "C",
    "domain": "HD1",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 4.0,
    "raw_value": 85.0,
    "four_star_line": 85.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": null,
    "prior_year_measure_id": null,
    "yoy_change": null,
    "series_break": true,
    "series_break_kind": "new_measure",
    "series_break_note": "CMS changed this measure this year; last year's star is not comparable"
   },
   {
    "measure_id": "C06",
    "measure_identity_key": "c:monitoring_physical_activity",
    "measure_name": "Monitoring Physical Activity",
    "canonical_name": "Monitoring Physical Activity",
    "cmit_number": "00450-01-C-PARTC",
    "part": "C",
    "domain": "HD1",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 3.0,
    "raw_value": 50.0,
    "four_star_line": 53.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": 3.0,
    "prior_year_measure_id": "C04",
    "yoy_change": 0.0
   },
   {
    "measure_id": "C07",
    "measure_identity_key": "c:special_needs_plan_snp_care_management",
    "measure_name": "Special Needs Plan (SNP) Care Management",
    "canonical_name": "Special Needs Plan (SNP) Care Management",
    "cmit_number": "00685-01-C-PARTC",
    "part": "C",
    "domain": "HD2",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 4.0,
    "raw_value": 83.0,
    "four_star_line": 73.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": 4.0,
    "prior_year_measure_id": "C05",
    "yoy_change": 0.0
   },
   {
    "measure_id": "C08",
    "measure_identity_key": "c:care_for_older_adults_medication_review",
    "measure_name": "Care for Older Adults - Medication Review",
    "canonical_name": "Care for Older Adults - Medication Review",
    "cmit_number": "00110-01-C-PARTC",
    "part": "C",
    "domain": "HD2",
    "weight": 1.0,
    "direction": "higher",
    "star_value": 5.0,
    "raw_value": 98.0,
    "four_star_line": 93.0,
    "four_star_op": ">=",
    "four_star_ladder": "ALL",
    "prior_year_star": 4.0,
    "prior_year_measure_id": "C06",
    "yoy_change": 1.0
   },
   {
    "measure_id": "C09",
    "measure_identity_key": "c:care_for_older_adults_pain_assessment",
    "measure_name": "Care for Older Adults - Pain Assessment",
    "canonical_name": "Care for Older Adults - Pain Assessment",
    "cmit_number": "00111-01-C-PARTC",
    "part": "C",
    "domain": "HD2",
    "weight": 1.0,
    "direction": "higher",
    "star_value
…

What comes back

Sources

Known limits (2)

1. 1Stars are contract-level (no plan_id).
2. 2Measure set + weights are methodology-versioned per rating_year; a measure retired or added between years has no YoY counterpart (null change).