# Medicare Advantage organizations with internal criteria postings

URL: https://docs.healthcare.dev/reference/medicare-advantage/medicare-advantage-organizations-with-internal-criteria-postings

```http
GET https://api.healthcare.dev/v1/medicare-advantage/plans
```

Pro plan and up (below: a few preview calls a month, then 403 `plan-upgrade-required`). Preview: not available yet. Medicare Advantage organizations whose public internal coverage criteria posting we hold, with the contracts we know for each (any of them can be looked up), how many services and procedure codes the posting covers, and its pages. Filter by text (`q`: organization name or id, or a contract such as `H1036`). Sorted by name. Then `GET /v1/medicare-advantage/{plan_id}/criteria`.

Requires an API key: `Authorization: Bearer hdev_live_...`. See [Authentication](/authentication).

## Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `q` | string | no | Organization name or id, or a contract (`H1036`) | `humana` |
| `limit` | integer | no | Page size (max 100) | `25` |
| `cursor` | string | no | Opaque cursor from `links.next` |  |
| `view` | "compact" \| "standard" \| "full" | no | How much of each record to return (default `full`). `compact`: `id`, `name`, `contracts` (fewest tokens, for agents). `standard`: every field except `posting_urls`. `full`: every field. | `compact` |
| `fields` | string | no | Comma-separated fields to return instead of a view. Valid fields: `id`, `name`, `applies_to`, `contracts`, `service_count`, `code_count`, `posting_urls`, `updated_date`. | `id,name,contracts` |

## Examples

**curl**

```sh
curl "https://api.healthcare.dev/v1/medicare-advantage/plans?q=humana&limit=25" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

**TypeScript**

```ts
const res = await fetch("https://api.healthcare.dev/v1/medicare-advantage/plans?q=humana&limit=25", {
  headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os
import requests

res = requests.get("https://api.healthcare.dev/v1/medicare-advantage/plans?q=humana&limit=25", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()
```

## Response

Organizations, by name

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "applies_to": "all_ma_plans",
      "contracts": [
        "string"
      ],
      "service_count": 1,
      "code_count": 1,
      "posting_urls": [
        "string"
      ],
      "updated_date": "2026-10-01"
    }
  ],
  "meta": {
    "source": "cms-icd10",
    "data_version": "2026.1",
    "retrieved_at": "2026-10-24T12:00:00Z",
    "license": "Public domain (CMS). Reference data, not medical advice."
  },
  "links": {
    "self": "/v1/medicare-advantage/plans?q=humana&limit=25",
    "next": "/v1/medicare-advantage/plans?q=humana&limit=25&cursor=eyJrIjoiRTExLjkifQ"
  }
}
```

### Fields

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Organization id, e.g. `humana` |
| `name` | string | yes |  |
| `applies_to` | "all_ma_plans" | yes |  |
| `contracts` | string[] | yes | Its Medicare Advantage contracts we know; each can be looked up by its id too |
| `service_count` | integer | yes | Services (policies) we serve for it |
| `code_count` | integer | yes | Distinct procedure codes its posting lists |
| `posting_urls` | string (uri)[] | yes | Its public pages listing the policies |
| `updated_date` | string \| null (date) | yes | The most recent policy date its posting shows |

## Errors

Errors are `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). Branch on `type`, not on `title`. See [Errors](/errors).

| Status | `type` | When |
| --- | --- | --- |
| 400 | `invalid-request` | A parameter or the body failed validation; `errors` lists each field. |
| 401 | `unauthorized` | Missing, malformed or revoked API key. |
| 403 | `plan-upgrade-required` | The plan doesn't include this feature; `required_plan` names the plan that does. |
| 404 | `not-found` | No record with that id (retired records are still returned). |
| 429 | `rate-limited / quota-exceeded` | Too many requests per second (retry after `Retry-After`), or the monthly quota is used up. |
| 503 | `dataset-unavailable / unavailable` | The dataset has no published version yet, or the service is degraded. |