# get_plan_network

Get Plan Network · v0.2.0 · medicare

The provider network a Medicare Advantage plan publishes: the NPIs its directory lists for a plan year (2026 or 2027), by contract or CMS plan id, with the source of every listing (the payer's own Plan-Net API, the printed directory, a name match to NPPES with its grade, or the Medicare Plan Finder export), the counts by source and grade, and a page of listings with name, specialty, location and the file and page each came from. Filter by state, ZIP or specialty.

Use cases: 'How many providers does H5959 list for 2027?'; 'Which cardiologists are in H5938's network in Tallahassee?'; 'Is this plan's directory API-served or printed?'.

Membership is DISTINCT NPIs, never row counts. Name-matched rows are flagged by grade and never presented as printed; listings whose name resolves to no single NPI are kept without an NPI and are not members. A contract with no rows is UNCOVERED (the open-gap list), never 'no network'. 2027 rows carried back from a 2026 directory are labelled (plan_key_basis). The publish is pinned by dataset_id.

SOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (the Data Tracker's directory build; every row names its url, page and raw_sha256).

**Inputs.**
- `contract_id`: CMS contract id (H5938). One of contract_id / cms_plan_id.
- `cms_plan_id`: CMS plan id H1234-001 or H1234-001-000 (contract-plan[-segment]).
- `plan_year` (required): 2026 or 2027 (the directory year).
- `state`: 2-letter state of the listed location; optional.
- `zip5`: 5-digit ZIP of the listed location; optional.
- `specialty`: Specialty as printed (contains match); optional.
- `limit`: Listings to return (default 50, max 500); counts are always whole.

**Known limits.**
- Coverage: 99.1% of 2026 MA members and 96.1% of 2027 members from 2027 sources (stage 21, 2026-11-02); the open-gap contracts (HCSC, Geisinger 2027, Highmark Wholecare, Elderplan, Mercy Care, Elevate, CarePartners CT, six thin Elevance contracts) are UNCOVERED and answer NO_COVERAGE.
- Listings whose printed name does not resolve to a single NPI (about 11.3M rows, grade C or D, mostly Humana PDFs) are kept without an NPI and are not counted as members.
- Matched grade N rows can lack city, state and ZIP; page is a string.
- 42 contracts' (1,132,045 members') 2027 rows are their 2026 directory applied through the CMS crosswalk (plan_key_basis *_2026_plan_via_crosswalk): labelled, not a 2027 directory.

**A real answer** (customer seat, 1.19 s, args `{"contract_id":"H5938","plan_year":2027,"limit":5}`):

```json
{
 "value": {
  "found": false,
  "not_found_reason": "query_failed",
  "query": {
   "contract_id": "H5938",
   "plan_year": 2027,
   "limit": 5
  },
  "dataset_id": "7bceef45cc9e5910e64caa428a1f3e40869f91d149c4e19f08cc55f5e468ba7c",
  "query_ids": []
 },
 "unit": "plan_network",
 "vintage": null,
 "source": {
  "dataset": "MA plan networks, 2026 and 2027 (Data Tracker): plan year x CMS plan x NPI x listed location",
  "publisher": "vlada",
  "catalog_updated_at": "2026-11-02"
 },
 "caveats": [],
 "response_hash": "a38a4df116e0dac275e5762743df6de0743e0062f1adbd238b5d50f43b293c0e",
 "semantic_version": 1,
 "tool_version": "get_plan_network@0.2.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "plan_network",
  "scope": {
   "tool": "get_plan_network",
   "filters": {
    "contract_id": "H5938",
    "plan_year": 2027,
    "limit": 5
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included.",
 "evidence": {
  "sources": [
   {
    "dataset": "MA plan networks, 2026 and 2027 (Data Tracker): plan year x CMS plan x NPI x listed location",
    "publisher": "vlada",
    "catalog_updated_at": "2026-11-02"
   }
  ],
  "response_hash": "a38a4df116e0dac275e5762743df6de0743e0062f1adbd238b5d50f43b293c0e"
 },
 "freshness": {
  "state": "unknown",
  "why": "This tool does not report an edition for its answer, and the door could not derive one from what the answer reads. Treat the result as current to no stated date."
 }
}
```

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