# Releases and what changed

URL: https://docs.healthcare.dev/reference/datasets/releases-and-what-changed

```http
GET https://api.healthcare.dev/v1/datasets/{dataset}/releases
```

Every published release of a dataset, newest first, with how many records it added, changed (revised) and retired, when the source published it and when we did. On every plan. The records themselves are in the change feed (`changes` links to `/v1/changes?dataset=&version=`, Builder and up). Retired records stay answerable with `status: retired` and, where known, `replaced_by`.

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

## Path parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `dataset` | string | yes | Dataset id from `/v1/datasets` | `icd10cm` |

## Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `limit` | integer | no | Page size, 1 to 100 (default 25) | `25` |
| `cursor` | string | no | Opaque cursor from `links.next` |  |
| `version` | string | no | Only this release (`data_version`) | `fy2027` |

## Examples

**curl**

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

**TypeScript**

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

## Response

Releases, newest first

```json
{
  "data": [
    {
      "dataset": "string",
      "version": "string",
      "status": "current",
      "effective_date": "2026-10-01",
      "published_at": "2026-10-24T12:00:00Z",
      "source_published_at": "2026-10-24T12:00:00Z",
      "source_published_basis": "last-modified",
      "lag_hours": 0,
      "baseline": true,
      "records": 1,
      "added": 1,
      "changed": 1,
      "retired": 1,
      "changes": "string"
    }
  ],
  "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/datasets/icd10cm/releases?limit=25",
    "next": "/v1/datasets/icd10cm/releases?limit=25&cursor=eyJrIjoiRTExLjkifQ"
  }
}
```

### Fields

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `dataset` | string | yes |  |
| `version` | string | yes | The release's `data_version` |
| `status` | "current" \| "superseded" | yes | `current` is the version served now; older releases are `superseded` |
| `effective_date` | string (date) | yes | Date the release takes effect |
| `published_at` | string (date-time) | yes | When we published it |
| `source_published_at` | string \| null (date-time) | yes | When the source published it |
| `source_published_basis` | "last-modified" \| "metadata" \| "file-name" \| "detected" \| null | yes | Where `source_published_at` comes from: the source file's `Last-Modified`, the source's own metadata (an API or index date), the date in the release's file name, or `detected` (the source gives no date: the first time our pipeline saw the release, an estimate) |
| `lag_hours` | number \| null | yes | Hours from the source publishing this release to us publishing it |
| `baseline` | boolean | yes | The first load of the dataset: every record counts as added and the change feed has no rows for it |
| `records` | integer \| null | yes | Records in the release, retired ones included |
| `added` | integer | yes | Records new in this release |
| `changed` | integer | yes | Records revised in this release |
| `retired` | integer | yes | Records retired in this release |
| `changes` | string \| null | yes | The release's records in the change feed (`/v1/changes`, Builder and up); null for a baseline |

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