get_hos

Get Hos

What it answers

Returns a Medicare Advantage contract's CMS Health Outcomes Survey (HOS) rates across the four survey topics (fall_risk_management, urinary_incontinence, osteoporosis_testing, physical_activity), each with the two reported rates and the year-over-year change. Filter by contract_id (required) + optional year (defaults to the latest; report years 2019-2025).

RETURNS a detail payload, not a topic count: value.topics is the per-topic row list (topic, report_year, rate1, rate2, rate3, rate1_yoy), value.summary rolls it up (topic_count, which topics reported, the highest and lowest rate1), value.row_counts carries matched / returned / truncated and value.query the filters applied. `limit` bounds the rows (default 200, max 2000).

HOS is the beneficiary-survey companion to the chart-abstracted HEDIS rates and feeds several Part C Star measures. rate1/rate2 are the survey's two published rates for the topic (e.g. the share who reported the issue and the share who discussed it with a provider); see the CMS HOS documentation for exact definitions. Pair with get_stars. A contract id with no HOS rows returns found=false with a not_found_reason.

SOURCE: CMS Health Outcomes Survey (HOS) Public Use File.

Inputs

contract_id

string · required

limit

integer · optional

year

integer · 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_hos 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_hos \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"<contract_id>"}'

curl https://api.vladahealth.com/v1/tools/get_hos/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.hedis_hos_frm
medicare_silver.hedis_hos_mui
medicare_silver.hedis_hos_oto
medicare_silver.hedis_hos_pao

tables: medicare_silver.hedis_hos_frm · medicare_silver.hedis_hos_mui · medicare_silver.hedis_hos_oto · medicare_silver.hedis_hos_pao

Known limits

rate1/rate2 semantics are topic-specific; consult the CMS HOS documentation.

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.