# ACA marketplace plans

URL: https://docs.healthcare.dev/reference/marketplace/aca-marketplace-plans

```http
GET https://api.healthcare.dev/v1/marketplace/plans
```

Preview: not available yet (503 `dataset-unavailable` until it is released). Pro plan and up (below Pro: a few preview calls a month, then 403 `plan-upgrade-required`). Health plans sold on the ACA marketplace in the states on the federal platform (HealthCare.gov), from the CMS Exchange public use files for the plan year: issuer, metal level, plan type, service area, rating areas and the standard variant's deductible and out-of-pocket maximum. Filter by state, county (5-digit FIPS: plans whose service area covers it), metal level, plan type, market, dental or medical, and issuer. Sorted by plan id. Then `GET /v1/marketplace/plans/{plan_id}` for premiums by age and rating area, every variant's deductibles and out-of-pocket maximums, and benefits. Derived from the CMS Health Insurance Exchange public use files for the plan year, as CMS published them; not CMS data, and it may differ from what HealthCare.gov shows. Covers the states on the federal platform (HealthCare.gov), not states running their own exchange. Premiums are the issuer's monthly base rates by age and rating area before any subsidy. Check the issuer's documents (links) before relying on a detail.

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

## Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `state` | string | no | Two-letter state | `TX` |
| `county` | string | no | County FIPS code (5 digits): plans whose service area covers all or part of it | `48453` |
| `metal` | string | no | Metal level: `bronze`, `expanded_bronze`, `silver`, `gold`, `platinum`, `catastrophic`; dental `high` or `low` | `silver` |
| `plan_type` | string | no | `HMO`, `PPO`, `EPO`, `POS` or `Indemnity` | `HMO` |
| `market` | "individual" \| "shop" | no | `individual` or `shop` (small group) | `individual` |
| `dental` | "true" \| "false" | no | `true`: stand-alone dental plans only; `false`: medical only | `true` |
| `issuer` | string | no | HIOS issuer id (5 digits) | `29418` |
| `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`, `issuer`, `metal_level`, `plan_type`, `cost_sharing` (fewest tokens, for agents). `standard`: every field except `links`. `full`: every field. | `compact` |
| `fields` | string | no | Comma-separated fields to return instead of a view. Valid fields: `id`, `plan_year`, `name`, `issuer`, `state`, `market`, `dental_only`, `metal_level`, `plan_type`, `exchange`, `network_id`, `service_area`, `rating_areas`, `cost_sharing`, `links`, `effective_date`, `expiration_date`. | `id,name,issuer` |

## Examples

**curl**

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

**TypeScript**

```ts
const res = await fetch("https://api.healthcare.dev/v1/marketplace/plans?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/marketplace/plans?limit=25", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()
```

## Response

Plans, by id

```json
{
  "data": [
    {
      "id": "string",
      "plan_year": 1,
      "name": "string",
      "issuer": {
        "id": "string",
        "name": "string"
      },
      "state": "string",
      "market": "individual",
      "dental_only": true,
      "metal_level": "string",
      "plan_type": "string",
      "exchange": "on_and_off",
      "network_id": "string",
      "service_area": {
        "id": "string",
        "name": "string",
        "covers_entire_state": true,
        "county_count": 1
      },
      "rating_areas": [
        "string"
      ],
      "cost_sharing": {
        "variant_id": "string",
        "deductible": 0,
        "moop": 0
      },
      "links": {
        "formulary_url": "string",
        "brochure_url": "string",
        "summary_of_benefits_url": "string",
        "enrollment_payment_url": "string"
      },
      "effective_date": "2026-10-01",
      "expiration_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/marketplace/plans?limit=25",
    "next": "/v1/marketplace/plans?limit=25&cursor=eyJrIjoiRTExLjkifQ"
  }
}
```

### Fields

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Plan id (HIOS standard component id), e.g. `29418TX0140108` |
| `plan_year` | integer | yes |  |
| `name` | string | yes |  |
| `issuer` | MarketplaceIssuer | yes |  |
| `state` | string | yes |  |
| `market` | MarketplaceMarket | yes | `individual` market, or `shop` (the Small Business Health Options Program) |
| `dental_only` | boolean | yes | A stand-alone dental plan |
| `metal_level` | string | yes | `bronze`, `expanded_bronze`, `silver`, `gold`, `platinum`, `catastrophic`; dental plans `high` or `low` |
| `plan_type` | string | yes | As published: `HMO`, `PPO`, `EPO`, `POS`, `Indemnity` |
| `exchange` | "on_and_off" \| "on" \| "off" | yes | Offered on the exchange, off it, or both |
| `network_id` | string \| null | yes |  |
| `service_area` | object | yes |  |
| `rating_areas` | string[] | yes | Rating areas the plan has premiums for |
| `cost_sharing` | MarketplaceCostSharing | yes | The individual in-network deductible and out-of-pocket maximum of the plan's standard variant (`-01` on exchange, else `-00`): the combined medical and drug amount when the plan integrates them, else the medical one. Every variant's full amounts are in `variants` |
| `links` | MarketplaceLinks | yes | The issuer's own pages, as listed in the plan attributes file (links only) |
| `effective_date` | string \| null (date) | yes |  |
| `expiration_date` | string \| null (date) | yes |  |

## 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. |