Get Benefit Change
get_benefit_changeThe locked 2027 Medicare Advantage benefit tables in one call: what each benefit was in 2026 and what it is in 2027 for the SAME members, member-weighted from the CMS Plan Benefit Package filings and CMS September 2026 county enrollment, inside ONE product type, for the market or a parent organization, nationally, in a state or in a county. Premium, MOOP, the medical and Part D deductibles, the medical copays and coinsurance, the Part D tier cost shares, dental / OTC / hearing / eyewear / flex card dollars and offered shares, the Part B giveback and the supplemental services.
ARGUMENTS: product_type (required unless group_by='product_type': non-SNP HMO | non-SNP PPO | D-SNP HMO | D-SNP PPO | C-SNP HMO | C-SNP PPO | I-SNP HMO | I-SNP PPO; 'ALL' is refused, types are never pooled), geography (national | state | county; inferred from the place when omitted), state (two letters), county (the name as CMS spells it, e.g. 'Maricopa', with state) or county_ssa (five digits, e.g. '03060'), parent (the parent organization; a partial name matches, e.g. 'UnitedHealth'), plan_type (default 'ALL'; HMO | HMOPOS | Local PPO | Regional PPO), group_by (none | parent | state | county | plan_type | product_type; state needs geography national, county needs geography state), benefits ('key' default | 'all' | a comma-separated list of benefit names, listed in value.benefits), limit (rows, default 50, max 500, largest 2026 membership first).
RETURNS value.summary (the market of the scope: every benefit for the scope's members) and value.rows (one per group, or per matching parent). Each row: members_2026 (every September 2026 member), members_continuing (the members on both sides of the change), plans, thin (true when the value rests on plans covering under 70% of the members or fewer than five plans) and, per benefit, {2026, 2027_same_members, change, coverage_2026, coverage_2027, 2026_all_members, unit}: 2026 is the continuing members' 2026 design, 2027_same_members those same members' 2027 design, change = 2027_same_members minus 2026; 2026_all_members is every 2026 member, context only, never one side of a change. coverage is the share of the row's members the value describes. A null value is unknown (no member filed it), never $0. Percent benefits are served 0-100. When an allowance is asked, like_for_like carries its dollars on the paired members (same form both years) with the share whose design changed form, which is a design change, never a raise or a cut.
D-SNP figures are the FILED design: a full dual generally pays $0 under Medicaid; the full-dual reading is the Plan Value tool's full-dual column. Employer group plans and stand-alone Part D are not in the tables.
SOURCE: Vlada locked benefit tables (Edition 1.1) from the CMS Plan Benefit Package filings, CMS county enrollment, the plan service area file and the CMS plan crosswalk.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| state | No | ||
| county | No | ||
| parent | No | ||
| benefits | No | key | |
| group_by | No | none | |
| geography | No | ||
| plan_type | No | ALL | |
| county_ssa | No | ||
| product_type | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | ||
| as_of | No | ||
| value | Yes | ||
| source | Yes | ||
| status | No | complete | |
| caveats | No | ||
| failure | No | ||
| quality | No | ||
| refusal | No | ||
| vintage | No | as_restated | |
| audit_id | Yes | UUID; ties to medicare_silver.audit_log row. | |
| signature | No | ||
| tenant_id | No | Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers. | |
| timestamp | Yes | ||
| confidence | No | ||
| data_as_of | No | ||
| request_id | Yes | ||
| methodology | No | ||
| snapshot_set | Yes | {table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2. | |
| tool_version | Yes | ||
| response_hash | Yes | SHA-256 of canonicalized form per M-2 §2.4. | |
| result_status | Yes | ||
| vintage_basis | No | default_unmeasured | |
| as_of_asserted | No | ||
| as_of_observed | No | ||
| parse_revision | No | ||
| as_of_effective | No | ||
| freshness_state | No | unknown | |
| methodology_era | No | ||
| confidence_basis | No | ||
| semantic_version | Yes | ||
| invariants_applied | No | ||
| finality_confidence | No | ||
| cms_vintage_sequence | Yes | ||
| parser_artifact_hash | Yes | ||
| methodology_blend_factors | No | ||
| parser_artifact_hash_basis | No | not_evaluated |