Look up cms provider dataset

---
name: look-up-cms-provider-dataset
description: When the user asks about CMS Medicare or Medicaid provider quality data — dialysis facility ratings, home health agency performance, hospice characteristics, patient experience surveys — reach for the CMS Provider Data API metastore. Dataset metadata, download links, and data dictionaries via one unauthenticated GET.
---

## When to use this skill

When the user asks about CMS Medicare or Medicaid provider quality data — dialysis facility ratings, home health agency performance, hospice characteristics, patient experience surveys — and needs to find the right dataset, get a download URL, or understand what columns a dataset contains. This is the catalog and metadata layer; it gives you dataset identifiers, descriptions, CSV download links, and PDF data dictionary links. For querying individual facility records from within a dataset, use the CMS Provider Data API datastore endpoints. For beneficiary-level claims data, this is the wrong skill.

## Your best first call

```bash
curl "https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/59mq-zhts"
```

No auth. No key. Returns a single DCAT dataset object. Replace `59mq-zhts` with any CMS Provider Data dataset identifier to look up that dataset. The response follows the DCAT standard — the same metadata schema used across data.gov catalogs.

Key fields an agent uses:

- `title` — human-readable name (e.g. "Patient survey (ICH CAHPS) - Facility")
- `description` — what the dataset measures and who it covers
- `theme` — array of care-area categories (e.g. `["Dialysis facilities"]`)
- `keyword` — searchable tags (e.g. `["Patient Survey", "Patient Experience of Care"]`)
- `distribution[0].downloadURL` — direct link to the CSV file with all facility-level records
- `distribution[0].describedBy` — URL to the PDF data dictionary explaining every column name
- `modified` — when CMS last updated the source data
- `released` — when the current snapshot became publicly available
- `nextUpdateDate` — CMS-specific extension to DCAT; when the next refresh is expected

Three date fields have distinct meanings: `issued` is the original publication date, `modified` is the internal update, and `released` is when the snapshot went public. A recent `modified` with an older `released` means the data is still in CMS's internal review — the typical gap is about six weeks.

## Fallbacks (when the best call isn't enough)

- **Need to discover which datasets exist for a care area** → `https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items` returns all 233 datasets. Filter locally on the `theme` field — there is no server-side search or filter parameter. Fetch this once per session and cache it; the response is ~500 KB.

- **Need individual facility records, not just metadata** → The `distribution[0].downloadURL` in the metadata response links to a full CSV. Download and parse that file — the metastore does not serve individual records.

## Pitfalls

- Dataset identifiers (`59mq-zhts`, `23ew-n7w9`) are opaque strings with no semantic meaning — they cannot be guessed or derived from dataset titles. Discover them from the catalog listing or from the dataset's landing page at `data.cms.gov/provider-data/dataset/{identifier}`.
- `downloadURL` contains a content-hash path segment that changes on every data refresh. Never hardcode it — resolve through the metastore immediately before downloading.
- The catalog listing returns all 233 datasets in one response with no server-side filtering. Do not attempt to pass theme or keyword as URL parameters; the endpoint does not support them.
- `nextUpdateDate` is advisory — CMS sometimes publishes updates days after the listed date.

## One-line summary for the user

I can look up CMS provider quality datasets and get their CSV download links via the CMS Provider Data API — no auth, but dataset identifiers are opaque so you may need to browse the catalog first.