get_market_share

What it answers

1. 1Returns a Medicare Advantage plan's or contract's county-level enrollment and its SHARE of the local MA market: for each county, the plan's enrollees, the county's total MA enrolled and Medicare-eligible population, the MA penetration rate, the plan's share of county MA enrollment, and the year-over-year change in the plan's county enrollment.
2. 2Filter by contract_id (required) + optional plan_id (plan vs contract total), optional state (2-letter, e.g. 'FL'), and optional month ('2024-03'); defaults to the latest available month.
3. 3RETURNS an actual SHARE with the arithmetic disclosed, not a raw headcount: value.summary.share_pct is the footprint share, and it always ships alongside its numerator (share_numerator_plan_enrollees) and its denominator (share_denominator_county_ma_enrolled), so nobody has to trust a bare percentage.
4. 4The denominator is the total MA enrollment of the counties this plan actually operates in for the month in scope, NOT the national MA market. value.counties is the per-county row list (plan enrollees, county MA enrolled, county eligibles, penetration, share_pct, yoy_change), largest first; value.row_counts carries matched / returned / truncated and value.query the resolved month.
5. 5`limit` bounds the county list (default 200, max 2000).
6. 6This is the geography + competition lens; pair with get_enrollment for the plan/contract totals.
7. 7Suppressed county cells (CMS redacts under 11) come back with null enrollees and null share, never zero, and the summary carries a [low, high] bound on the numerator that brackets them.
8. 8A contract id with no county rows returns found=false with a not_found_reason.
9. 9SOURCE: CMS Monthly Enrollment by CPSC + MA State/County Penetration.

Inputs (5)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
get_market_share(contract_id="H1036", limit=5)

curl -X POST https://api.vladahealth.com/v1/tools/get_market_share \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"H1036","limit":5}'

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

A real answer

{
 "value": {
  "found": true,
  "not_found_reason": null,
  "summary": {
   "contract_id": "H1036",
   "plan_id": null,
   "grain": "contract",
   "state": null,
   "month": "2026-10-01",
   "share_pct": 3.24,
   "share_definition": "plan enrollees in the counties in scope / total MA enrollment of those same counties, for the month in scope",
   "share_numerator_plan_enrollees": 856969,
   "share_numerator_basis": "bound_floor_published_plus_1_per_suppressed_county",
   "share_numerator_published_cells": 856312,
   "share_denominator_county_ma_enrolled": 26489733,
   "share_numerator_bound": [
    856969,
    862882
   ],
   "share_pct_bound": [
    3.24,
    3.26
   ],
   "counties_medicare_eligibles": 50029743,
   "footprint_ma_penetration_pct": 52.95,
   "county_count": 1006,
   "suppressed_county_count": 657,
   "best_county_share_pct": 40.82,
   "median_county_share_pct": 6.13,
   "largest_county": {
    "state": "FL",
    "county": "Broward",
    "plan_enrollees": 88173,
    "share_pct": 35.59
   },
   "unit": "percent_of_county_ma_enrollment"
  },
  "counties": [
   {
    "state": "FL",
    "county": "Broward",
    "plan_enrollees": 88173,
    "county_ma_enrolled": 247731,
    "county_eligibles": 383369,
    "penetration": 0.6462,
    "share_pct": 35.59,
    "yoy_change": 11388,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Miami-Dade",
    "plan_enrollees": 65998,
    "county_ma_enrolled": 397170,
    "county_eligibles": 528794,
    "penetration": 0.7511,
    "share_pct": 16.62,
    "yoy_change": 10681,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Palm Beach",
    "plan_enrollees": 52582,
    "county_ma_enrolled": 179484,
    "county_eligibles": 371693,
    "penetration": 0.4829,
    "share_pct": 29.3,
    "yoy_change": 2638,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Hillsborough",
    "plan_enrollees": 40211,
    "county_ma_enrolled": 172547,
    "county_eligibles": 274972,
    "penetration": 0.6275,
    "share_pct": 23.3,
    "yoy_change": 4387,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Pinellas",
    "plan_enrollees": 35353,
    "county_ma_enrolled": 160487,
    "county_eligibles": 265560,
    "penetration": 0.6043,
    "share_pct": 22.03,
    "yoy_change": 2021,
    "county_ma_is_group_figure": false
   }
  ],
  "row_counts": {
   "counties": {
    "matched": 1006,
    "returned": 5,
    "truncated": true,
    "limit": 5,
    "kept": "head"
   }
  },
  "query": {
   "contract_id": "H1036",
   "plan_id": null,
   "grain": "contract",
   "state": null,
   "month": "2026-10-01",
   "limit": 5
  },
  "query_id": "6cbad2cb-aa86-4233-9a31-ad924caed7eb"
 },
 "unit": "market_share_detail",
 "result_status": "answered",
 "methodology_era": null,
 "methodology_blend_factors": null,
 "source": {
  "source_url": "medicare://get_market_share"
 },
 "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": "65641d3dce1dec285d899b1bdea42f34a48a1d42c9e6184e25ee05a9142e60ad",
 "semantic_version": 1,
 "tool_version": "0.3.1",
 "parser_artifact_hash": "0b11193fb97519397f53ffe2917938b1bf95f408fccb5bae6d356b17ef22a148",
 "parser_artifact_hash_basis": "tool_source_sha256",
 "signature": null,
 "tenant_id": "probe-customer-canary",
 "status": "complete",
 "audit_id": "20c32f7c-c513-4d31-9421-20fda03154e8",
 "timestamp": "2026-11-09T21:36:54.622950Z",
 "request_id": "e9c3ca90-15fe-45d5-b90e-62ec96cdbf40",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "market_share_detail",
  "scope": {
   "tool": "get_market_share",
   "filters": {
    "contract_id": "H1036",
    "limit": 5
   }
  }
 },
 "method": "Read from the CMS publication at the contract level. The published values are reported as published, with no adjustment or modelling applied.",
 "evidence": {
  "query_id": "6cbad2cb-aa86-4233-9a31-ad924caed7eb",
  "response_hash": "65641d3dce1dec285d899b1bdea42f34a48a1d42c9e6184e25ee05a9142e60ad",
  "audit_id": "20c32f7c-c513-4d31-9421-20fda03154e8",
  "request_id": "e9c3ca90-15fe-45d5-b90e-62ec96cdbf40"
 }
}

What comes back

Sources

Known limits (2)

1. 1County cells under 11 enrollees are CMS-redacted (null enrollees, null share).
2. 2Share = plan county enrollees / total MA enrolled in county (penetration file).