Get Negotiated Rate
get_negotiated_rateGet the negotiated rate a specific payer pays a specific NPI for a specific billing code, in a state. Resolves at query time through the canonical graph + inverted indexes (no precomputed edge table) and returns the most provider-specific rate with source lineage, methodology, evidence type, and Medicare-PUF corroboration. UHC custom codes are resolved automatically. Covers all built payers. Near-zero dollar rates (positive, under $1 — the ghost class the benchmark path excludes) are never picked over a plausible rate; if one is all that matched, it is served flagged is_ghost_candidate at confidence 0.2 with a caveat, never as a real price.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| npi | Yes | 10-digit provider NPI. This is the INSURER / Transparency-in-Coverage side — rates are keyed by NPI (Type 1 individual OR Type 2 facility/org), NOT by CCN. | |
| code | Yes | Billing code (CPT/HCPCS), e.g. '99213'. | |
| payer | Yes | Payer name or alias (e.g. 'cigna', 'aetna', 'uhc'). Must be a built payer; use find_data_sources to see which are available. | |
| state | No | 2-letter state, e.g. 'CA'. STRONGLY RECOMMENDED: resolution is state-scoped — without it you will usually get no_match. | |
| vintage | No | Optional payer data-build version (e.g. '2026-04'). Omit = latest built; for claim repricing, pin to the claim's service-date vintage to avoid a silent mismatch. | |
| methodology | No | Optional: narrow to ONE methodology (negotiated / percentage / per_diem / case_rate). Methodologies are NOT comparable — don't mix them. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | ||
| as_of | No | ||
| value | No | ||
| source | No | ||
| status | No | complete | |
| caveats | No | ||
| failure | No | ||
| quality | No | ||
| rate_id | No | ||
| refusal | No | ||
| vintage | No | ||
| no_match | No | ||
| explanation | No | ||
| methodology | No | ||
| tool_version | No | unknown | |
| response_hash | No | ||
| freshness_state | No | unknown | |
| code_resolved_to | No | ||
| semantic_version | No | ||
| payer_resolved_to | No | ||
| invariants_applied | No | ||
| facility_resolved_to | No |