> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Care Quality Ratings

> Look up official Medicare star ratings for a care facility.

Returns official star ratings of a US hospital, nursing home, home health agency, hospice or dialysis facility by CMS Certification Number or name, from the US Centers for Medicare & Medicaid Services: overall rating from 1 to 5, plus nursing home inspection, quality and staffing ratings. A null rating means the source published none.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**facility\_type** `string` *required*

Which register to read; each kind of facility is rated in its own dataset. One of `hospital`, `nursing_home`, `home_health`, `hospice`, `dialysis`.

**ccn** `string`

The facility CMS Certification Number (Medicare provider number). A CMS Certification Number is six digits or capital letters.

**facility\_name** `string`

Case-insensitive substring of the facility name. 3 to 100 characters.

**state** `string`

State abbreviation; only with facility\_name.

**limit** `integer`

Most facilities to return. From 1 to 10. Defaults to `5`.

<Snippet file="audit-context-params.mdx" />

<Snippet file="cached-record-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `company_care_quality`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.cached** `boolean`

`true` when the answer was served from OneShot's store of earlier lookups (or its own copy of a public dataset), `false` when the source was asked for this call

**data.fetched\_at** `string`

When the record was obtained from its source, as an ISO 8601 UTC time; equals `evidence.retrieved_at`

**data.evidence.source** `string`

The public body the data comes from. Always `US Centers for Medicare & Medicaid Services`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

For nursing homes, the date the source processed the register release that answered; null for other facility types, whose rows carry no date.

## Result

Nested under `data.result`.

**data.result.facility\_type** `string`

Facility type.

**data.result.rating\_name** `string`

Rating name.

**data.result.has\_more** `boolean`

Has more.

**data.result.facilities** `object[]`

Facilities.

**data.result.facilities\[].ccn** `string`

Ccn.

**data.result.facilities\[].name** `string`

Name.

**data.result.facilities\[].city** `string | null`

City. `null` when the source gives no value.

**data.result.facilities\[].state** `string | null`

State. `null` when the source gives no value.

**data.result.facilities\[].zip\_code** `string | null`

Zip code. `null` when the source gives no value.

**data.result.facilities\[].ownership** `string | null`

Ownership. `null` when the source gives no value.

**data.result.facilities\[].chain** `string | null`

Chain. `null` when the source gives no value.

**data.result.facilities\[].overall\_rating** `integer | null`

Overall rating. `null` when the source gives no value.

**data.result.facilities\[].overall\_rating\_footnote** `string | null`

Overall rating footnote. `null` when the source gives no value.

**data.result.facilities\[].component\_ratings** `object | null`

Component ratings. `null` when the source gives no value.

**data.result.facilities\[].component\_ratings.health\_inspection** `integer | null`

Health inspection. `null` when the source gives no value.

**data.result.facilities\[].component\_ratings.quality\_measures** `integer | null`

Quality measures. `null` when the source gives no value.

**data.result.facilities\[].component\_ratings.long\_stay\_quality** `integer | null`

Long stay quality. `null` when the source gives no value.

**data.result.facilities\[].component\_ratings.short\_stay\_quality** `integer | null`

Short stay quality. `null` when the source gives no value.

**data.result.facilities\[].component\_ratings.staffing** `integer | null`

Staffing. `null` when the source gives no value.

**data.result.facilities\[].special\_focus\_status** `string | null`

Special focus status. `null` when the source gives no value.

**data.result.facilities\[].abuse\_cited** `boolean | null`

Abuse cited. `null` when the source gives no value.

**data.result.facilities\[].rating\_period** `string | null`

Rating period. `null` when the source gives no value.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-care-quality \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "facility_type": "hospital",
    "ccn": "240010"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/company-care-quality", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "facility_type": "hospital",
    "ccn": "240010"
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/company-care-quality', {
  facility_type: 'hospital',
  ccn: '240010'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "company_care_quality",
    "result": {
      "facility_type": "hospital",
      "rating_name": "Overall hospital quality star rating",
      "has_more": false,
      "facilities": [
        {
          "ccn": "240010",
          "name": "MAYO CLINIC HOSPITAL ROCHESTER",
          "city": "ROCHESTER",
          "state": "MN",
          "zip_code": "55902",
          "ownership": "Voluntary non-profit - Church",
          "chain": null,
          "overall_rating": 5,
          "overall_rating_footnote": null,
          "component_ratings": null,
          "special_focus_status": null,
          "abuse_cited": null,
          "rating_period": null
        }
      ]
    },
    "evidence": {
      "source": "US Centers for Medicare & Medicaid Services",
      "source_kind": "public",
      "retrieved_at": "2026-10-27T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-27T12:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* rating\_name identifies the rating for each facility\_type: hospital overall quality, nursing home overall five-star, home health patient care quality, hospice family caregiver survey summary, or dialysis facility five-star.
* Names match substrings; use has\_more and the CCN to distinguish facilities. No match completes with facilities: \[].
* Use place\_hospitals to list hospitals in a ZIP code and company\_medicare\_ownership for ownership details. Only the current release is served; history begins with our first observation.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.