# Coverage

`GET https://api.inplan.io/v1/coverage`

What we hold: for each market, state, insurer and plan year, how many plans have provider listings, and the date we read them. Filter by market, state and year.

Free plan and up · 1 call. Source: https://inplan.io/docs/api/coverage

## When to use it

Use it to decide which states and insurers to offer checks for, or to show users how current the data is for their state.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `market` | query | string · `aca` or `ma` | Optional | `aca` or `ma`. Omit for both. Example: `ma`. |
| `state` | query | string | Optional | Only this state (2-letter code). Example: `OH`. |
| `year` | query | integer | Optional | Only this plan year. Example: `2026`. |

## Request

curl:

```bash
curl https://api.inplan.io/v1/coverage \
  -H "Authorization: Bearer $INPLAN_KEY" \
  -G -d state=OH
```

JavaScript:

```javascript
const url = new URL("https://api.inplan.io/v1/coverage");
url.search = new URLSearchParams({ state: "OH" });

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.INPLAN_KEY}` },
});
const body = await res.json();
console.log(body.data.summary);
```

Python:

```python
import os, requests

res = requests.get(
    "https://api.inplan.io/v1/coverage",
    params={"state": "OH"},
    headers={"Authorization": f"Bearer {os.environ['INPLAN_KEY']}"},
    timeout=10,
)
body = res.json()
print(body["data"]["summary"])
```

## Response fields

Every response has the envelope `request_id`, `data_as_of`, `data`, `sources` and `notes`. Fields of `data`:

| Field | Type | Description |
| --- | --- | --- |
| `filters` | object | The filters you sent (`null` when not sent). |
| `filters.market` | string \| null | `aca`, `ma` or `null`. |
| `filters.state` | string | The state filter. |
| `filters.year` | integer \| null | The plan year filter. |
| `markets` | string[] | Markets with listings for these filters. |
| `summary` | object | Totals by market, then by plan year. |
| `summary.{market}` | object | `aca` or `ma`. |
| `summary.{market}.{year}` | object | Totals for one plan year. |
| `summary.{market}.{year}.states` | integer | States with listings. |
| `summary.{market}.{year}.insurers` | integer | Insurers or organizations with listings. |
| `summary.{market}.{year}.plans` | integer | Plans with listings. |
| `summary.{market}.{year}.as_of` | date | The newest date we read a directory in this group. |
| `rows` | object[] | One row for each market, state, insurer and plan year with listings. |
| `rows[].market` | string | `aca` or `ma`. |
| `rows[].state` | string | 2-letter state code. |
| `rows[].insurer` | string | The insurer or organization name. |
| `rows[].plan_year` | integer | The plan year. |
| `rows[].plans` | integer | Plans with listings in this row. |
| `rows[].as_of` | date \| null | The date we read the directory for this row. |

## Responses

### 200

Totals in `summary`, one row per market, state, insurer and plan year in `rows` (shortened here).

Response (200 OK · application/json):

```json
{
  "request_id": "req_0U9QnpvGhkSal2Qg",
  "data_as_of": "2026-10-29",
  "data": {
    "filters": {
      "market": null,
      "state": "OH",
      "year": null
    },
    "markets": [
      "aca",
      "ma"
    ],
    "summary": {
      "aca": {
        "2026": {
          "states": 1,
          "insurers": 11,
          "plans": 189,
          "as_of": "2026-10-29"
        }
      },
      "ma": {
        "2027": {
          "states": 1,
          "insurers": 6,
          "plans": 45,
          "as_of": "2026-10-29"
        }
      }
    },
    "rows": [
      {
        "market": "aca",
        "state": "OH",
        "insurer": "Ambetter from Buckeye Health Plan",
        "plan_year": 2026,
        "plans": 16,
        "as_of": null
      },
      {
        "market": "aca",
        "state": "OH",
        "insurer": "Anthem Blue Cross and Blue Shield",
        "plan_year": 2026,
        "plans": 11,
        "as_of": "2026-07-27"
      },
      {
        "market": "aca",
        "state": "OH",
        "insurer": "Antidote Health Plan of Ohio, Inc.",
        "plan_year": 2026,
        "plans": 15,
        "as_of": "2026-10-28"
      }
    ]
  },
  "sources": [
    {
      "type": "insurer_directory",
      "description": "Provider network directories published by health insurers",
      "as_of": "2026-10-29"
    },
    {
      "type": "plan_catalog",
      "description": "Published health plan catalogs",
      "as_of": "2026-10-28"
    },
    {
      "type": "plan_directory",
      "description": "Provider network directories published by Medicare Advantage plans",
      "as_of": "2026-10-29"
    }
  ]
}
```

### 400

An invalid `market`, `state` or `year`.

Response (400 Bad Request · application/problem+json):

```json
{
  "type": "invalid_request",
  "title": "Invalid state",
  "status": 400,
  "detail": "`state` must be a 2-letter US state code; got \"XX\".",
  "instance": "/v1/coverage",
  "request_id": "req_O2YuV9GXYt2-y6DK",
  "docs": "https://inplan.io/docs/errors#invalid_request"
}
```

### 401

The `Authorization` header is missing or malformed, or the key is unknown or revoked.

Response (401 Unauthorized · application/problem+json):

```json
{
  "type": "unauthorized",
  "title": "Missing API key",
  "status": 401,
  "detail": "Send `Authorization: Bearer ip_live_...`.",
  "instance": "/v1/coverage",
  "request_id": "req_BylbsNzGqRikrP1Y",
  "docs": "https://inplan.io/docs/errors#unauthorized"
}
```

### 429

More requests a second than the key allows.

Response (429 Too Many Requests · application/problem+json):

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json; charset=utf-8
Retry-After: 1
RateLimit-Limit: 2
RateLimit-Remaining: 0
RateLimit-Reset: 1
RateLimit-Policy: 2;w=1;burst=5
X-Request-Id: req_TrHd8LO8HNbLoZ_D
```

```json
{
  "type": "rate_limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This key allows 2 requests per second.",
  "instance": "/v1/coverage",
  "request_id": "req_TrHd8LO8HNbLoZ_D",
  "docs": "https://inplan.io/docs/errors#rate_limited"
}
```

## Errors

Errors use `application/problem+json` (RFC 7807): `type`, `title`, `status`, `detail`, `instance`, `request_id`, `docs`. Other statuses this endpoint can return: `403` and `503`. See [Errors](https://inplan.io/docs/errors).

## Rate-limit headers

Every response that passes the key and plan checks carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`, `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset` and `X-Request-Id`. See [Rate limits and quotas](https://inplan.io/docs/rate-limits).