# get_enrollment

Get Enrollment · v0.4.0 · medicare

Returns CMS monthly enrollment for a Medicare Advantage plan or contract: the member count, the trend over time, and, at contract level, the MA-only vs Part-D split, plus org/parent and plan type. Filter by contract_id (required) + optional plan_id (plan grain vs contract total), and optional year ('2024') or month ('2024-03'); with neither, returns the latest month plus a trailing 13-month trend. Monthly coverage back to 2006. Every row carries the year-over-year change (yoy_change / yoy_pct) vs the same month one year earlier; plan rows carry the plan's SNP class (snp_type) when applicable.

RETURNS a detail payload, not a bare count: value.summary (latest_month, latest_enrollment, yoy_change / yoy_pct, ma_only_count / part_d_count, trend min/max and change over the window), value.months (the per-month trend rows), value.row_counts (matched / returned / truncated / limit) and value.query (the filters actually applied). `limit` bounds the trend rows returned (default 13 months, max 2000); a truncated list always carries a caveat.

Enrollment is the SPINE every other MA metric joins to (per-member, share-weighted). SUPPRESSION is honest: CMS redacts cells under 11 enrollees, which come back as count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell', never a zero, and the suppression caveat fires only when a returned month is actually redacted. A contract id that does not exist returns found=false with a not_found_reason, never a suppression story.

Pair with get_pbp_benefit or get_stars to weight or normalize by members. SOURCE: CMS Monthly Enrollment by Plan / by Contract.

**Inputs.**
- `contract_id` (required): 
- `plan_id`: 
- `year`: 
- `month`: 
- `limit`: 

**Known limits.**
- Cells under 11 enrollees are CMS-redacted: count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell'.
- MA-only vs Part-D split is contract-level only (omit plan_id to get it).
- County / market-share grain lives in enrollment_monthly_county (612M rows); this tool serves plan + contract totals.

**A real answer** (customer seat, 3.46 s, args `{"contract_id":"H1036","limit":5}`):

```json
{
 "value": {
  "found": true,
  "not_found_reason": null,
  "summary": {
   "grain": "contract",
   "contract_id": "H1036",
   "plan_id": null,
   "snp_type": null,
   "organization": "Humana",
   "parent_org": "Humana Inc.",
   "plan_name": null,
   "plan_type": "HMO/HMOPOS",
   "offers_part_d": true,
   "latest_month": "2026-10-01",
   "latest_enrollment": 859334,
   "unit": "enrollees",
   "yoy_change": 213333,
   "yoy_pct": 33.0,
   "ma_only_count": 3465,
   "part_d_count": 855869,
   "trend_start_month": "2026-06-01",
   "trend_end_month": "2026-10-01",
   "trend_min_enrollment": 845931,
   "trend_max_enrollment": 859334,
   "trend_change_over_window": 13403,
   "suppressed_month_count": 0
  },
  "months": [
   {
    "report_month": "2026-06-01",
    "enrollment_count": 845931,
    "enrollment_lower_bound": 845931,
    "enrollment_upper_bound": 845931,
    "enrollment_suppression_reason": "none",
    "ma_only_count": 3659,
    "part_d_count": 842272,
    "plan_type": "HMO/HMOPOS",
    "offers_part_d": true,
    "organization_marketing_name_raw": "Humana",
    "parent_org_raw": "Humana Inc.",
    "yoy_change": 195047,
    "yoy_pct": 30.0
   },
   {
    "report_month": "2026-07-01",
    "enrollment_count": 849463,
    "enrollment_lower_bound": 849463,
    "enrollment_upper_bound": 849463,
    "enrollment_suppression_reason": "none",
    "ma_only_count": 3608,
    "part_d_count": 845855,
    "plan_type": "HMO/HMOPOS",
    "offers_part_d": true,
    "organization_marketing_name_raw": "Humana",
    "parent_org_raw": "Humana Inc.",
    "yoy_change": 199496,
    "yoy_pct": 30.7
   },
   {
    "report_month": "2026-08-01",
    "enrollment_count": 853829,
    "enrollment_lower_bound": 853829,
    "enrollment_upper_bound": 853829,
    "enrollment_suppression_reason": "none",
    "ma_only_count": 3552,
    "part_d_count": 850277,
    "plan_type": "HMO/HMOPOS",
    "offers_part_d": true,
    "organization_marketing_name_raw": "Humana",
    "parent_org_raw": "Humana Inc.",
    "yoy_change": 206390,
    "yoy_pct": 31.9
   },
   {
    "report_month": "2026-09-01",
    "enrollment_count": 856349,
    "enrollment_lower_bound": 856349,
    "enrollment_upper_bound": 856349,
    "enrollment_suppression_reason": "none",
    "ma_only_count": 3498,
    "part_d_count": 852851,
    "plan_type": "HMO/HMOPOS",
    "offers_part_d": true,
    "organization_marketing_name_raw": "Humana",
    "parent_org_raw": "Humana Inc.",
    "yoy_change": 210325,
    "yoy_pct": 32.6
   },
   {
    "report_month": "2026-10-01",
    "enrollment_count": 859334,
    "enrollment_lower_bound": 859334,
    "enrollment_upper_bound": 859334,
    "enrollment_suppression_reason": "none",
    "ma_only_count": 3465,
    "part_d_count": 855869,
    "plan_type": "HMO/HMOPOS",
    "offers_part_d": true,
    "organization_marketing_name_raw": "Humana",
    "parent_org_raw": "Humana Inc.",
    "yoy_change": 213333,
    "yoy_pct": 33.0
   }
  ],
  "row_counts": {
   "months": {
    "matched": 5,
    "returned": 5,
    "truncated": false,
    "limit": 5,
    "kept": "tail"
   }
  },
  "query": {
   "contract_id": "H1036",
   "plan_id": null,
   "grain": "contract",
   "year": null,
   "month": null,
   "limit": 5
  },
  "query_id": "77437feb-4d20-4861-b416-010a03977cbe"
 },
 "unit": "enrollment_detail",
 "result_status": "answered",
 "methodology_era": null,
 "methodology_blend_factors": null,
 "source": {
  "source_url": "medicare://get_enrollment"
 },
 "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": "b8f263396d9e9c83fc0afc86d7c3c9838b2fc358519c80d9275b7eddb7e6909c",
 "semantic_version": 1,
 "tool_version": "0.4.0",
 "parser_artifact_hash": "0b11193fb97519397f53ffe2917938b1bf95f408fccb5bae6d356b17ef22a148",
 "parser_artifact_hash_basis": "tool_source_sha256",
 "signature": null,
 "tenant_id": "probe-customer-canary",
 "status": "complete",
 "audit_id": "2d9ca760-25e5-429b-ac9d-c555e84658c9",
 "timestamp": "2026-11-09T21:33:35.907514Z",
 "request_id": "bf50a9aa-a62b-4473-a1bc-c603066865a5",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "enrollment_detail",
  "scope": {
   "tool": "get_enrollment",
   "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": "77437feb-4d20-4861-b416-010a03977cbe",
  "response_hash": "b8f263396d9e9c83fc0afc86d7c3c9838b2fc358519c80d9275b7eddb7e6909c",
  "audit_id": "2d9ca760-25e5-429b-ac9d-c555e84658c9",
  "request_id": "bf50a9aa-a62b-4473-a1bc-c603066865a5"
 }
}
```

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