Prices
Hospital price transparency lines and the per-stay payer prices priced from hospitals' contract terms.
search_price_transparency
search_price_transparency reads the price files hospitals publish under CMS price transparency rules. You don't call it yourself. Your assistant does, from your question, and shows you what came back.
Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
apc | list of string | none | APC codes (Medicare outpatient payment groups). |
code_type | CPT | HCPCS | MS-DRG | APC | none | Only lines of this code type. |
codes | list of string | none | CPT, HCPCS or MS-DRG codes to look up. |
hospital_ids | list of string | none | Up to 25 hospital ids (UUIDs), as returned in the hospital_id field of earlier rows. |
limit | integer | 100 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
offset | integer | 0 | Rows to skip, for paging. |
priced_only | boolean | true | Hide lines that have no price. On by default. |
q | string | none | Search the service description, up to 200 characters. |
setting | inpatient | outpatient | none | Only inpatient or only outpatient lines. |
state | string | none | Two-letter US state, for example FL. A state on its own is not enough: add codes, apc, q or hospital_ids. |
A search needs a place and a narrowing. Give a two-letter state or a list of hospital_ids, and also at least one of codes, apc, q or hospital_ids. A whole state is not searchable, because it is millions of lines. If you leave the narrowing out, the tool answers with an error that says what to add, and your assistant will usually ask you.
Limits:
hospital_ids: at most 25.q: at most 200 characters.limit: 1 to 500, default 100.
A search that takes longer than 30 seconds is stopped with an error that says to narrow it (fewer hospitals, specific codes).
What comes back
The result has these top-level fields:
| Field | Meaning |
|---|---|
rows | The matching lines (identical lines appear once). |
hospitals | Each row's hospital_id mapped to that hospital's name, city and page_url (its page on CognitoLabs, which links the hospital's own price transparency page and price file). |
hospitals_without_rows | Present when you passed hospital_ids and some returned no line. |
count | How many rows are in this answer. |
truncated | true when the row limit was reached. Narrow the search to see the rest. |
locked | true when your plan only gets the free preview. |
negotiated_hidden | true on the free preview: negotiated and estimated rates are not included. |
note | Present when something about the answer needs saying, such as the preview limits. |
Each row is one published charge line (a hospital can publish several lines for the same code, by setting or billing class, written in lowercase). It carries the hospital_id (look the hospital up in hospitals, or pass the id back in hospital_ids) and the code, and the prices, in dollars rounded to cents:
| Field | Meaning |
|---|---|
gross_charge | The hospital's chargemaster list price. |
discounted_cash | The price the hospital publishes for self-pay patients. |
avg_negotiated_rate, min_negotiated_rate, max_negotiated_rate | Average, lowest and highest negotiated rate across the payers that hospital publishes for the code. |
payer_count, distinct_payer_count | How many payer entries stand behind the negotiated figures. |
avg_estimated_rate, estimated_payer_count | CMS estimated allowed amounts. These are a separate family. They are not negotiated rates, and the tool never blends them in. |
On the free preview you get 8 lines that have a gross or cash price, and the negotiated, estimated and payer-count fields are left out. See Plans & access.
Example questions
- What do hospitals in Tampa charge for a 99213 office visit?
- Compare negotiated rates for CPT 70553 (brain MRI) across Florida hospitals.
- What's the cash price for a 45378 colonoscopy at hospitals in Kansas?
- Which Atlanta hospital has the lowest gross charge for CPT 27447?
- Show outpatient MRI of the brain at these three hospitals, lowest cash price first.
market_price_stats
market_price_stats answers "what is the typical price of this code in this market" without searching the price files, so it comes back at once. Ask it for a state, a metro, or one hospital size class inside a metro. For one named hospital's own prices, your assistant uses search_price_transparency instead.
Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
bed_band | <50 | 50-99 | 100-199 | 200-399 | 400+ | none | |
codes | list of string | required | CPT, HCPCS or MS-DRG codes to look up. |
limit | integer | 100 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
metro | string | none | Metro area (CBSA) code, 5 digits, for example 12060 for Atlanta. Find it with find_metro. |
setting | inpatient | outpatient | none | Only inpatient or only outpatient lines. |
state | string | none | Two-letter US state, for example FL. A state on its own is not enough: add codes, apc, q or hospital_ids. |
Give one place: a two-letter state, or a metro (the CBSA code your assistant gets from find_metro). bed_band narrows a metro to hospitals of one size and needs metro. The bands, by bed count, are under 50, 50 to 99, 100 to 199, 200 to 399 and 400 or more. A hospital with no bed count is in the metro figures but in no band. Up to 25 codes per call.
What comes back
There is one list per price family: gross (the chargemaster list price), cash (the published self-pay price) and negotiated (the hospital's average across its payers). Each row has the code, code_type, setting, the number of hospitals, and the spread across those hospitals: p10, p25, median, p75, p90, min and max, in dollars.
Every hospital counts once, at its own average for the code, so a hospital with forty payer lines does not outweigh one with two. Only facility lines count, and prices under $1 are left out as placeholders. A code is listed only where at least two hospitals have a price for it; the others come back in missing_codes. as_of is the date the figures were built. They are rebuilt weekly and after each state's price files are reloaded.
On the free preview you get 8 rows per family and no negotiated list. See Plans & access.
Example questions
- What is the typical price of a 99213 in Florida?
- What do 200 to 399 bed hospitals in the Tampa metro charge for a brain MRI, and how wide is the range?
- Is the price of CPT 45378 in Kansas City higher at big hospitals than small ones?
get_drg_payer_prices
What each insurer pays a hospital per inpatient stay. Hospitals publish contract methods (a per diem, a percent of Medicare, a case rate); we price each one into a single case price per MS-DRG and payer. Loaded for Kansas, Georgia and Florida hospitals.
| Parameter | Type | Default | What it does |
|---|---|---|---|
drgs | list of string | none | MS-DRG codes to look up. |
hospital_ids | list of string | required | Up to 25 hospital ids (UUIDs), as returned in the hospital_id field of earlier rows. |
include_terms | boolean | false | Also return contract terms such as stop-loss and lesser-of. |
limit | integer | 50 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
payer | string | none | Only this insurer, as named in the data. |
Give one to five hospital_ids (from find_hospitals). limit is at most 500, default 50. Each row has drg, description, payer, case_price (median dollars per stay), pct_of_charges, estimated (true when a per diem was multiplied by the CMS average stay), families (the methods used) and gross_charge. With include_terms, terms lists the contract clauses we found (stop-loss, lesser-of, carve-outs), up to 100.
This is a paid dataset. The free preview is 8 rows that show which payers and methods we priced and the hospital's gross charge, without case_price or pct_of_charges, and no contract terms; locked is true; when it is, the answer carries a subscribe link your assistant shows you. See Plans & access.
Example questions
- What does Aetna pay Grady for DRG 470?
- Which insurer pays the most for a joint replacement at these two hospitals?
- Does this hospital have a stop-loss clause with Cigna?
get_hospital_payer_rates
What each insurer and plan pays one hospital for a code, read straight from the hospital's own price file. search_price_transparency gives you the average, lowest and highest across payers for a line; this tool gives you the row for each payer and plan behind those figures.
| Parameter | Type | Default | What it does |
|---|---|---|---|
codes | list of string | required | CPT, HCPCS or MS-DRG codes to look up. |
hospital_ids | list of string | required | Up to 25 hospital ids (UUIDs), as returned in the hospital_id field of earlier rows. |
include_percentages | boolean | true | |
limit | integer | 200 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
payer | string | none | Only this insurer, as named in the data. |
Give one to five hospital_ids (from find_hospitals) and one to 25 codes. A code is a CPT, HCPCS, MS-DRG or APC code. payer is optional and narrows the answer to one insurer: "Aetna" matches "Aetna PPO" and the other Aetna plans, whatever spelling the hospital used. include_percentages (default true) keeps or drops the rows priced as a percent. limit is 1 to 500, default 200.
The result has rows, count, truncated and hospitals (each hospital_id mapped to its name and city). Each row is one payer and plan on one line:
| Field | Meaning |
|---|---|
hospital_id, code, code_type, setting, billing_class | The line the rate belongs to. |
payer, carrier | The insurer's standard name and the company behind it, from the payer names we group hospitals' spellings into. A name we haven't grouped shows as published, with no carrier. |
plan | The plan name the hospital published. |
raw_payer | The payer name exactly as the hospital published it. |
negotiated_dollar | The negotiated rate in dollars, rounded to cents. |
negotiated_percentage | A negotiated rate published as a percent. It is a percent of gross_charge, and it never appears in negotiated_dollar. |
methodology, algorithm | How the hospital says the rate is set (case rate, per diem, percent of charges) and its algorithm text. |
estimated_amount | The CMS estimated allowed amount for that payer. It is a separate figure, not a negotiated rate. |
gross_charge | The line's chargemaster price. |
Rows come back sorted by code, hospital, then payer. To see the insurer's own filing of the same contract, ask for search_payer_rates next.
This is a paid dataset. A plan without public-data, or without a hospital or metro grant that covers every hospital you asked about, gets the free preview: 8 rows with payer, plan, methodology and the line's identifiers, without negotiated_dollar, negotiated_percentage, estimated_amount, gross_charge or algorithm. locked is true, and the answer carries a subscribe link your assistant shows you. See Plans & access.
Example questions
- What does each insurer pay Tampa General for 99285?
- Compare what Aetna and Cigna pay these two hospitals for a 70553 brain MRI.
- Is the Humana rate at this hospital published as dollars or as a percent of charges?