Get Hos
get_hosReturns 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| limit | No | ||
| contract_id | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | ||
| as_of | No | ||
| value | Yes | ||
| source | Yes | ||
| status | No | complete | |
| caveats | No | ||
| failure | No | ||
| quality | No | ||
| refusal | No | ||
| vintage | No | as_restated | |
| audit_id | Yes | UUID; ties to medicare_silver.audit_log row. | |
| signature | No | ||
| tenant_id | No | Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers. | |
| timestamp | Yes | ||
| confidence | No | ||
| data_as_of | No | ||
| request_id | Yes | ||
| methodology | No | ||
| snapshot_set | Yes | {table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2. | |
| tool_version | Yes | ||
| response_hash | Yes | SHA-256 of canonicalized form per M-2 §2.4. | |
| result_status | Yes | ||
| vintage_basis | No | default_unmeasured | |
| as_of_asserted | No | ||
| as_of_observed | No | ||
| parse_revision | No | ||
| as_of_effective | No | ||
| freshness_state | No | unknown | |
| methodology_era | No | ||
| confidence_basis | No | ||
| semantic_version | Yes | ||
| invariants_applied | No | ||
| finality_confidence | No | ||
| cms_vintage_sequence | Yes | ||
| parser_artifact_hash | Yes | ||
| methodology_blend_factors | No | ||
| parser_artifact_hash_basis | No | not_evaluated |