MedRates.fyi

Query US hospital price transparency data via the MedRates REST API. Search medical procedure prices, compare hospitals, filter by insurance plan and locatio...

Security Scan

The skill is an instruction-only wrapper for the MedRates REST API and its declared requirements and behavior are coherent with that purpose.

Purpose & Capability

Name/description match the SKILL.md: it documents HTTP endpoints on https://data.medrates.fyi, provides curl examples for searching prices and price-quote queries, and claims no required credentials for basic use. There are no unrelated binaries, extra cloud credentials, or surprising system-level demands.

Instruction Scope

Instructions are limited to querying the MedRates API (NLP search, price-quote, text search). They do not instruct reading local files or other system state. Note: the skill asks for user-supplied data such as latitude/longitude and payer/plan information—these can be sensitive (medical/PHI) and will be sent to the remote API; the SKILL.md references an 'Authentication' section for higher rate limits (not included in the excerpt) which could introduce optional token usage.

Install Mechanism

No install spec and no code files — instruction-only. This is low-risk from a code-installation perspective because nothing will be written to disk or fetched by the installer.

Credentials

The skill declares no required environment variables or credentials, which is consistent with the statement that no API key is required for basic use. However, the SKILL.md mentions an 'Authentication' section for higher rate limits; if that requires an API key/token it is not declared in the skill metadata. Optional auth would be reasonable, but the absence of declared optional env vars is a mild documentation inconsistency to be aware of.

Persistence & Privilege

always is false, no install writes, and the skill is user-invocable/default-invocation allowed. It does not request persistent privileges or modify other skill/system configs.

Assessment

This skill is an instruction-only client for data.medrates.fyi and appears coherent for price-lookup tasks. Before installing: verify you trust the domain (https://data.medrates.fyi), because queries will send any supplied location and payer details (potentially sensitive medical information) to that external API; check the SKILL.md's full 'Authentication' section or the service website for optional API key usage and whether you need to supply a token (the skill metadata does not declare any env vars). If you plan to look up real patient data, avoid sending identifying fields (name, SSN) and consider anonymizing locations (use zip codes rather than full addresses) or obtain patient consent. Finally, because this skill has no code files, static scanners had nothing to analyze — the runtime privacy risk is the network calls the SKILL.md instructs the agent to make.

MedRates Hospital Price Transparency

Query real US hospital prices — negotiated insurance rates, cash discounts, and gross charges — from CMS-mandated machine-readable files.

Base URL: https://data.medrates.fyi

All endpoints return JSON. No API key is required for basic use (see Authentication for higher rate limits).

Quick Start

The fastest way to answer "how much does X cost?" is the NLP search:

curl -X POST https://data.medrates.fyi/api/search/nlp/grouped \
  -H "Content-Type: application/json" \
  -d '{"query": "brain MRI near San Jose with Blue Cross PPO"}'

For exact code lookups with multi-hospital price comparison:

curl "https://data.medrates.fyi/api/price-quote?codes=70551,70552&lat=37.33&lng=-121.89&payer=Blue+Cross&plan_type=PPO"

Coverage Limitation

This data covers US hospitals only — prices published by licensed US hospitals under the Hospital Price Transparency Rule. It does not include prices from:

• Non-US healthcare providers (any country outside the United States)
• Independent/freestanding imaging centers (MRI, CT, X-ray)
• Ambulatory surgery centers (ASCs)
• Urgent care clinics
• Physician offices and medical groups
• Independent laboratories
• Other non-hospital providers

For outpatient procedures (MRIs, CTs, colonoscopies, minor surgeries), independent freestanding facilities often charge significantly less than hospital outpatient departments. When presenting hospital prices to users, note that non-hospital alternatives may exist at lower cost.

Endpoints

1. Natural Language Search (Grouped) — POST /api/search/nlp/grouped

Best for: Answering questions in plain English. Resolves procedure names to codes, geocodes cities, and groups results by billing code.

Request body (JSON):

Field	Type	Required	Description
query	string	yes	Natural language, e.g. "knee replacement in Palo Alto with Aetna PPO"
lat	float	no	Patient latitude (improves geo-sorting)
lng	float	no	Patient longitude
radius_miles	float	no	Geo cutoff in miles
payer	string	no	Insurance company name, e.g. "Blue Cross", "Aetna"
plan_type	string	no	Plan type, e.g. "PPO", "HMO"
plan_name	string	no	Exact plan name for precise matching
setting	string	no	"inpatient" or "outpatient"
code_type	string	no	"CPT", "HCPCS", or "MS-DRG"
codes	string[]	no	Pre-resolved codes (skips LLM extraction — faster)
procedure	string	no	Pre-extracted procedure name (skips LLM extraction)
codes_per_page	int	no	Code groups per page (default 10, max 50)
hospitals_per_code	int	no	Hospitals per code group (default 5, max 20)
page	int	no	Page number for pagination (default 1)

Response: Groups of results by billing code, each with a list of hospitals sorted by price. Includes extracted (what the NLP parsed), resolved (codes found), and groups[] with hospital pricing.

Pro tip: If you already know the CPT codes, pass them in codes to skip the LLM extraction step — it's faster and uses less rate limit budget.

2. Price Quote — GET /api/price-quote

Best for: Precise multi-code cost estimates at nearby hospitals. Returns per-hospital totals.

Param	Type	Required	Description
codes	string	yes	Comma-separated CPT/HCPCS codes, e.g. "70551,70552,70553"
lat	float	yes	Patient latitude
lng	float	yes	Patient longitude
radius_miles	float	no	Search radius (default 25)
payer	string	no	Insurance payer name
plan_category	string	no	Plan category filter: "Commercial", "Medicare", "Medicaid", or "Other"
plan_type	string	no	Plan type, e.g. "PPO", "HMO", "EPO"
plan_name	string	no	Exact plan name
drg_codes	string	no	Comma-separated MS-DRG codes for inpatient bundled pricing
include_bundle	bool	no	Include ancillary codes (anesthesia, facility fees) in estimate
limit	int	no	Max hospitals (default 5)

Response: Hospitals sorted by total_estimate (cheapest first). Each hospital has items[] with per-code prices, total_estimate, distance_miles, and in_network status. Negotiated/estimated-rate items include plan_category (Commercial, Medicare, Medicaid, Other) when a payer is specified; cash/standard-charge-only items will not have this field.

3. Text Search — GET /api/search

Best for: Direct code lookups or keyword searches when you already know the CPT/HCPCS code.

Param	Type	Required	Description
q	string	yes	Code (e.g. "70551") or keyword (e.g. "MRI brain"). Min 2 chars.
code_type	string	no	"CPT", "HCPCS", "MS-DRG"
hospital_id	int	no	Filter to a specific hospital
payer_name	string	no	Filter by payer name
plan_name	string	no	Filter by exact plan name
setting	string	no	"inpatient" or "outpatient"
zip_code	string	no	US ZIP code for geo filtering
lat	float	no	Latitude for geo-sorting
lng	float	no	Longitude for geo-sorting
radius_miles	float	no	Radius cutoff
page	int	no	Page number (default 1)
page_size	int	no	Results per page (default 100)

Response: Flat list of charge items with gross_charge, discounted_cash_price, min_negotiated_rate, max_negotiated_rate, hospital info, and optional payer_rate when filtered by payer.

4. Hospitals — GET /api/hospitals

Returns all hospitals with campus locations and coordinates. Use hospital IDs to filter other endpoints.

5. Payers — GET /api/payers

Returns all insurance payer + plan combinations. Optional ?hospital_id=N to filter by hospital.

6. Stats — GET /api/stats/public

Returns database summary: hospital count, procedure count, plan count, covered states.

Deep Links

When presenting results to users, link to the web UI for visual exploration:

• Procedure page: https://data.medrates.fyi/code/{CODE_TYPE}/{CODE} (e.g. /code/CPT/70551)
• Hospital search: https://data.medrates.fyi/search?q={QUERY}
• All hospitals: https://data.medrates.fyi/hospitals

Workflow Recommendations

1. User asks a vague question (e.g. "how much is an MRI?"): Use POST /api/search/nlp/grouped with their query. Include lat/lng if you know their location.

2. User has specific codes (e.g. "price for CPT 27447"): Use GET /api/price-quote with codes=27447 and their coordinates.

3. User wants to compare insurance plans: First call GET /api/payers to find available plans, then use price_quote or search/nlp/grouped with the payer/plan filters.

4. User asks about a specific hospital: Call GET /api/hospitals to find the hospital ID, then use GET /api/search with hospital_id.

Authentication

All endpoints work without authentication. Anonymous rate limits are sufficient for casual use.

Rate Limits (Anonymous)

Tier	Limit	Endpoints
Standard	30/min	/api/search
Expensive	10/min	/api/search/nlp, /api/search/nlp/grouped
Landing	20/min	/api/price-quote
Utility	15/min	/api/hospitals, /api/payers, /api/stats/public

Authenticated Access (Higher Limits)

If you hit rate limits, your human should request an API access token by emailing [e-mail] or visiting medrates.fyi/api-access.

Once you have a JWT token, include it in requests:

Authorization: Bearer <token>

Authenticated users get significantly higher rate limits (e.g. 200/min standard, 60/min expensive) based on their plan. The token's rate_limit claim determines the multiplier applied to each tier.

Rate Limit Headers

All responses include standard rate limit headers:

• X-RateLimit-Limit — requests allowed in the window
• X-RateLimit-Remaining — requests left
• X-RateLimit-Reset — seconds until the window resets
• Retry-After — seconds to wait (only on 429 responses)

When you receive a 429 Too Many Requests response, wait for the Retry-After period. If you're consistently rate-limited, ask your human to request API access.

Response Notes

• All prices are in USD
• gross_charge is the hospital's list price (chargemaster)
• discounted_cash_price is what uninsured patients pay
• min_negotiated_rate / max_negotiated_rate are the range across all insurers
• When filtering by payer, payer_rate is the specific negotiated rate
• Price data comes from CMS-mandated hospital price transparency files, updated as hospitals publish new MRFs
• CPT codes are copyright American Medical Association — display the disclaimer when showing CPT data to users