get_pbp_benefit

Get PBP Benefit

What it answers

Returns Plan Benefit Package (PBP) benefit detail for an MA plan for a specific category (dental, inpatient_hospital, ER, etc.).

Polymorphic — pass `category` to route to the right semantic view. All categories share the standard envelope: cost_share_string, copay_amount, coinsurance_pct, limit_text, auth_required, referral_required, network_type, max_oop_applies + category-specific extension fields (e.g., dental_sub_benefit).

Required: contract_id, plan_id, payment_year, category. The category must be one of the 19 supported (call get_pbp_benefit_catalog to list).

The response `value` is the full benefit-detail object: `rows` (every matched benefit row, with cost sharing, limits, and category extension fields), `row_count`, the resolved `category`/`human_label`/`view_fqn`, the `audit_chain` (CMS source URL + sha256 per row), and a `summary` sub-field carrying the single-row headline cost_share_string (or the row count when multiple sub-benefit rows match) for a quick read. Plus any methodology-shift caveats (e.g., 'B16 dental restructured CY2025' when querying dental for 2025+). Cross-year queries get cross-shift caveats.

Live categories auto-discovered from contract registry — call get_pbp_benefit_catalog to enumerate at runtime. As of 2026-05-25 the 19 onboarded categories are: dental, vision, hearing, otc, moop, transportation, b19_combined_package, inpatient_hospital, emergency_urgent, health_professionals, outpatient_hospital, partb_rx_drugs, snf, home_health, dme, renal_dialysis, supplemental_other, section_c_pos_oon, partd_drugs.

A contract/plan/year/category combination with NO rows is REFUSED with code NO_DATA, not answered with an empty complete: the refusal states what was searched and routes to get_landscape (the plan ids that really exist for that contract and year) and get_pbp_benefit_catalog (the categories). One view is read, so a nonexistent plan and a plan with nothing in this category cannot be told apart here; the refusal says so.

Inputs

category

string · required

contract_id

string · required

payment_year

integer · required

plan_id

string · required

segment_id

string · optional

Call it

From an agent: connect the Vlada MCP once (one click for Claude, ChatGPT, Cursor, VS Code) and ask in plain English; the agent selects get_pbp_benefit when the question fits. From code: the same tool over REST with an API key. The schema endpoint needs no key.

curl -X POST https://api.vladahealth.com/v1/tools/get_pbp_benefit \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<category>","contract_id":"<contract_id>","payment_year":2026,"plan_id":"<plan_id>"}'

curl https://api.vladahealth.com/v1/tools/get_pbp_benefit/schema      # the JSON schema, no auth
# MCP endpoint (Streamable HTTP): https://mcp.vladahealth.com/mcp

What comes back

Typed rows plus provenance on every answer: the public source file, its vintage, the methodology, and a response_hash you can replay. Prove and replay tools turn any number into a re-runnable receipt. A number the data cannot support comes back as “not in the data”, never as zero.

Sources behind it

medicare_silver.fact_ma_landscape
medicare_silver.pbp_mrx
medicare_silver.pbp_mrx_tier
medicare_silver.pbp_section_a
medicare_silver.pbp_section_b10_amb_trans
medicare_silver.pbp_section_b11_dme_prosth_orth_sup
medicare_silver.pbp_section_b12_renal_dialysis
medicare_silver.pbp_section_b13_other_services
medicare_silver.pbp_section_b14_preventive
medicare_silver.pbp_section_b15_partb_rx_drugs
medicare_silver.pbp_section_b16_dental
medicare_silver.pbp_section_b17_eye_exams_wear
medicare_silver.pbp_section_b18_hearing_exams_aids
medicare_silver.pbp_section_b1a_inpat_hosp
medicare_silver.pbp_section_b1b_inpat_hosp_psych
medicare_silver.pbp_section_b20
medicare_silver.pbp_section_b2_snf
medicare_silver.pbp_section_b3_cardiac_rehab
medicare_silver.pbp_section_b4_emerg_urgent
medicare_silver.pbp_section_b5_partial_hosp
medicare_silver.pbp_section_b6_home_health
medicare_silver.pbp_section_b7_health_prof
medicare_silver.pbp_section_b8_clin_diag_ther
medicare_silver.pbp_section_b9_outpat_hosp
medicare_silver.pbp_section_c_oon
medicare_silver.pbp_section_c_pos
medicare_silver.pbp_section_d
medicare_semantic.vw_pbp_b19_combined_package
medicare_semantic.vw_pbp_cardiac_pulmonary_rehab
medicare_semantic.vw_pbp_clinical_diagnostic_therapeutic
medicare_semantic.vw_pbp_dental
medicare_semantic.vw_pbp_dme
medicare_semantic.vw_pbp_emergency_urgent
medicare_semantic.vw_pbp_health_professionals
medicare_semantic.vw_pbp_hearing
medicare_semantic.vw_pbp_home_health
medicare_semantic.vw_pbp_inpatient_hospital
medicare_semantic.vw_pbp_inpatient_psychiatric
medicare_semantic.vw_pbp_moop
medicare_semantic.vw_pbp_otc
medicare_semantic.vw_pbp_outpatient_hospital
medicare_semantic.vw_pbp_partb_rx_drugs
medicare_semantic.vw_pbp_partd_drugs
medicare_semantic.vw_pbp_partd_tier
medicare_semantic.vw_pbp_partial_hospitalization
medicare_semantic.vw_pbp_preventive
medicare_semantic.vw_pbp_renal_dialysis
medicare_semantic.vw_pbp_section_c_pos_oon
medicare_semantic.vw_pbp_snf
medicare_semantic.vw_pbp_supplemental_other
medicare_semantic.vw_pbp_transportation
medicare_semantic.vw_pbp_vision

tables: medicare_silver.fact_ma_landscape · medicare_silver.pbp_mrx · medicare_silver.pbp_mrx_tier · medicare_silver.pbp_section_a · medicare_silver.pbp_section_b10_amb_trans · medicare_silver.pbp_section_b11_dme_prosth_orth_sup · medicare_silver.pbp_section_b12_renal_dialysis · medicare_silver.pbp_section_b13_other_services · medicare_silver.pbp_section_b14_preventive · medicare_silver.pbp_section_b15_partb_rx_drugs · medicare_silver.pbp_section_b16_dental · medicare_silver.pbp_section_b17_eye_exams_wear · medicare_silver.pbp_section_b18_hearing_exams_aids · medicare_silver.pbp_section_b19a_model_test_vbid_uf · medicare_silver.pbp_section_b19b_model_test_vbid_uf · medicare_silver.pbp_section_b1a_inpat_hosp · medicare_silver.pbp_section_b1b_inpat_hosp_psych · medicare_silver.pbp_section_b20 · medicare_silver.pbp_section_b2_snf · medicare_silver.pbp_section_b3_cardiac_rehab · medicare_silver.pbp_section_b4_emerg_urgent · medicare_silver.pbp_section_b5_partial_hosp · medicare_silver.pbp_section_b6_home_health · medicare_silver.pbp_section_b7_health_prof · medicare_silver.pbp_section_b8_clin_diag_ther · medicare_silver.pbp_section_b9_outpat_hosp · medicare_silver.pbp_section_c_oon · medicare_silver.pbp_section_c_pos · medicare_silver.pbp_section_d

views: medicare_semantic.vw_pbp_ambulance · medicare_semantic.vw_pbp_b19_combined_package · medicare_semantic.vw_pbp_cardiac_pulmonary_rehab · medicare_semantic.vw_pbp_clinical_diagnostic_therapeutic · medicare_semantic.vw_pbp_combined_supplemental · medicare_semantic.vw_pbp_dental · medicare_semantic.vw_pbp_dme · medicare_semantic.vw_pbp_dsnp_cost_share · medicare_semantic.vw_pbp_emergency_urgent · medicare_semantic.vw_pbp_health_professionals · medicare_semantic.vw_pbp_hearing · medicare_semantic.vw_pbp_home_health · medicare_semantic.vw_pbp_inpatient_hospital · medicare_semantic.vw_pbp_inpatient_psychiatric · medicare_semantic.vw_pbp_meals · medicare_semantic.vw_pbp_moop · medicare_semantic.vw_pbp_otc · medicare_semantic.vw_pbp_outpatient_hospital · medicare_semantic.vw_pbp_partb_rx_drugs · medicare_semantic.vw_pbp_partd_drugs · medicare_semantic.vw_pbp_partd_tier · medicare_semantic.vw_pbp_partial_hospitalization · medicare_semantic.vw_pbp_plan_deductible · medicare_semantic.vw_pbp_plan_premium · medicare_semantic.vw_pbp_preventive · medicare_semantic.vw_pbp_renal_dialysis · medicare_semantic.vw_pbp_section_c_pos_oon · medicare_semantic.vw_pbp_snf · medicare_semantic.vw_pbp_supplemental_other · medicare_semantic.vw_pbp_transportation · medicare_semantic.vw_pbp_vision

Known limits

PBP-PK-PRE-2010
PBP-QUARTERLY-PRE-2018

As of the 2026-09-19 build of the served surface · machine-readable catalog · the live server may run a different version; the schema endpoint above is authoritative for what is deployed.