cmu-delphi · JavierMtzRdz · Aug 25, 2026
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -6,6 +6,9 @@ nav_order: 4
 
 # Other Endpoints
 
+> **Active endpoints are part of the legacy V4 API, which is being phased out.** See the [V4 to V5 Migration Guide](v5_migration.md) for details on the Delphi V5 transition.
+{: .warning }
+
 This is the home of [Delphi](https://delphi.cmu.edu/)'s epidemiological data
 API for tracking infectious diseases such as influenza, dengue,
 and norovirus. Note that additional data, including most COVID-19 signals, is

diff --git a/docs/api/covidcast-signals/doctor-visits.md b/docs/api/covidcast-signals/doctor-visits.md
@@ -5,6 +5,9 @@ grand_parent: Main Endpoint (COVIDcast)
 nav_order: 1
 ---
 
+> **Heads up:** This COVIDcast source is part of the legacy V4 API, which is being phased out. An actively maintained equivalent is available in V5 under the source `claims_data_outpatient`. See the [V4 to V5 Migration Guide](../v5_migration.md) for full details.
+{: .warning }
+
 # Doctor Visits
 {: .no_toc}
 

diff --git a/docs/api/covidcast-signals/hospital-admissions.md b/docs/api/covidcast-signals/hospital-admissions.md
@@ -5,6 +5,9 @@ grand_parent: Main Endpoint (COVIDcast)
 nav_order: 1
 ---
 
+> **Heads up:** This COVIDcast source is part of the legacy V4 API, which is being phased out. An actively maintained equivalent is available in V5 under the source `claims_data_inpatient`. See the [V4 to V5 Migration Guide](../v5_migration.md) for full details.
+{: .warning }
+
 # Hospital Admissions
 {: .no_toc}
 

diff --git a/docs/api/covidcast-signals/nchs-mortality.md b/docs/api/covidcast-signals/nchs-mortality.md
@@ -5,6 +5,9 @@ grand_parent: Main Endpoint (COVIDcast)
 nav_order: 1
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Check the [V4 to V5 Source Coverage](../v5_signals.md#v4-to-v5-source-coverage) table or query [`/epidata/v5/metadata/`](../v5_meta.md) directly (more up to date) for whether this source is available in V5 yet. See the [V4 to V5 Migration Guide](../v5_migration.md) for full details.
+{: .warning }
+
 # NCHS Mortality Data
 {: .no_toc}
 

diff --git a/docs/api/covidcast-signals/nhsn.md b/docs/api/covidcast-signals/nhsn.md
@@ -4,6 +4,10 @@ parent: Data Sources and Signals
 grand_parent: Main Endpoint (COVIDcast)
 nav_order: 1
 ---
+
+> **Heads up:** This COVIDcast source is part of the legacy V4 API, which is being phased out. An actively maintained equivalent is available in V5 under the source `nhsn`. See the [V4 to V5 Migration Guide](../v5_migration.md) for full details.
+{: .warning }
+
 # National Healthcare Safety Network Respiratory Hospitalizations
 {: .no_toc}
 

diff --git a/docs/api/covidcast-signals/nssp.md b/docs/api/covidcast-signals/nssp.md
@@ -4,6 +4,10 @@ parent: Data Sources and Signals
 grand_parent: Main Endpoint (COVIDcast)
 nav_order: 1
 ---
+
+> **Heads up:** This COVIDcast source is part of the legacy V4 API, which is being phased out. An actively maintained equivalent is available in V5 under the source `nssp`. See the [V4 to V5 Migration Guide](../v5_migration.md) for full details.
+{: .warning }
+
 # National Syndromic Surveillance Program Emergency Department Visits
 {: .no_toc}
 

diff --git a/docs/api/covidcast-signals/quidel.md b/docs/api/covidcast-signals/quidel.md
@@ -5,6 +5,9 @@ grand_parent: Main Endpoint (COVIDcast)
 nav_order: 1
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Check the [V4 to V5 Source Coverage](../v5_signals.md#v4-to-v5-source-coverage) table or query [`/epidata/v5/metadata/`](../v5_meta.md) directly (more up to date) for whether this source is available in V5 yet. See the [V4 to V5 Migration Guide](../v5_migration.md) for full details.
+{: .warning }
+
 # Quidel
 {: .no_toc}
 

diff --git a/docs/api/covidcast.md b/docs/api/covidcast.md
@@ -6,6 +6,9 @@ nav_order: 3
 
 # Main Epidata API
 
+> **This endpoint (`/epidata/covidcast/`) is part of the legacy V4 API, which is being phased out.** The legacy V4 API includes this endpoint. See the [V4 to V5 Migration Guide](v5_migration.md) for guidance on migrating your queries to the [Delphi V5 API](v5.md).
+{: .warning }
+
 This legacy Epidata API endpoint was formerly called COVIDcast.
 
 This is the documentation for accessing all Delphi's indicators via the `covidcast` endpoint of [Delphi](https://delphi.cmu.edu/)'s

diff --git a/docs/api/covidcast_meta.md b/docs/api/covidcast_meta.md
@@ -5,6 +5,9 @@ grand_parent: Main Endpoint (COVIDcast)
 nav_order: 0
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Please use the [V5 Metadata Discovery Endpoints](v5_meta.md) instead of this endpoint. See the [V4 to V5 Migration Guide](v5_migration.md) for full details.
+{: .warning }
+
 # COVIDcast Metadata
 
 The COVIDcast metadata endpoint (endpoint `covidcast_meta`) provides a list of all

diff --git a/docs/api/covidcast_signals.md b/docs/api/covidcast_signals.md
@@ -5,6 +5,10 @@ nav_order: 3
 has_children: true
 
 ---
+
+> **Heads up:** The legacy v4 Epidata API is being phased out. See the [V4 to V5 Migration Guide](v5_migration.md) and the [V4 to V5 Source Coverage](v5_signals.md#v4-to-v5-source-coverage) table for full details.
+{: .warning }
+
 # Delphi's COVID-19 Data Sources and Signals
 
 Delphi's COVID-19 Surveillance Streams data includes the following data sources.

diff --git a/docs/api/flusurv.md b/docs/api/flusurv.md
@@ -5,6 +5,9 @@ grand_parent: Other Endpoints
 nav_order: 3
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Check the [V4 to V5 Source Coverage](v5_signals.md#v4-to-v5-source-coverage) table or query [`/epidata/v5/metadata/`](v5_meta.md) directly (more up to date) for whether this source is available in V5 yet. See the [V4 to V5 Migration Guide](v5_migration.md) for full details.
+{: .warning }
+
 # FluSurv
 {: .no_toc}
 

diff --git a/docs/api/fluview.md b/docs/api/fluview.md
@@ -5,6 +5,9 @@ grand_parent: Other Endpoints
 nav_order: 1
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Check the [V4 to V5 Source Coverage](v5_signals.md#v4-to-v5-source-coverage) table or query [`/epidata/v5/metadata/`](v5_meta.md) directly (more up to date) for whether this source is available in V5 yet. See the [V4 to V5 Migration Guide](v5_migration.md) for full details.
+{: .warning }
+
 # FluView (ILINet)
 {: .no_toc}
 

diff --git a/docs/api/fluview_clinical.md b/docs/api/fluview_clinical.md
@@ -5,6 +5,9 @@ grand_parent: Other Endpoints
 nav_order: 2
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Check the [V4 to V5 Source Coverage](v5_signals.md#v4-to-v5-source-coverage) table or query [`/epidata/v5/metadata/`](v5_meta.md) directly (more up to date) for whether this source is available in V5 yet. See the [V4 to V5 Migration Guide](v5_migration.md) for full details.
+{: .warning }
+
 # FluView Clinical
 {: .no_toc}
 

diff --git a/docs/api/fluview_meta.md b/docs/api/fluview_meta.md
@@ -5,6 +5,9 @@ grand_parent: Other Endpoints
 nav_order: 1
 ---
 
+> **Heads up:** The legacy v4 Epidata API is being phased out. Check the [V4 to V5 Source Coverage](v5_signals.md#v4-to-v5-source-coverage) table or query [`/epidata/v5/metadata/`](v5_meta.md) directly (more up to date) for whether this source is available in V5 yet. See the [V4 to V5 Migration Guide](v5_migration.md) for full details.
+{: .warning }
+
 # FluView Metadata
 {: .no_toc}
 

diff --git a/docs/api/v5.md b/docs/api/v5.md
@@ -31,6 +31,8 @@ Additionally, various metadata routes are available for querying schema columns,
 
 Many database and query patterns in the legacy API (the [COVIDcast endpoint](covidcast.md)) emerged from the rapid demands of the COVID-19 response. However, this legacy setup introduced critical bottlenecks. To address those limitations, the V5 API improves data quality, speeds up development times, and enhances query performance.
 
+See the [V4 to V5 Migration Guide](v5_migration.md) for guidance on migrating existing queries.
+
 ## Authentication and Rate Limits
 
 Anyone may access the Epidata API anonymously without providing any personal data. Anonymous API access is currently rate-limited and restricted to public datasets. The rate limits are 60 requests/hour general, with an additional limit of 5 requests/minute on `/archive/` and 3 requests/minute on `/snapshot/`.

diff --git a/docs/api/v5_meta.md b/docs/api/v5_meta.md
@@ -0,0 +1,20 @@
+---
+title: V5 Metadata Discovery Endpoints
+parent: Delphi V5 API
+nav_order: 2
+---
+
+# V5 Metadata Discovery Endpoints
+
+The V5 API provides metadata endpoints under `https://delphi.cmu.edu/epidata/v5/metadata/` to explore available sources, signals, geographies, schemas, and date ranges.
+
+| Endpoint | Description | Parameters | Example Query |
+| :--- | :--- | :--- | :--- |
+| [`/epidata/v5/metadata/`](https://delphi.cmu.edu/epidata/v5/metadata/) | Overview of active sources, signals, geographic levels, and date ranges. | `source` (optional) | [`?source=nssp`](https://delphi.cmu.edu/epidata/v5/metadata/?source=nssp) |
+| [`geo_signals/`](https://delphi.cmu.edu/epidata/v5/metadata/geo_signals/) | Active sources and signals available for a given location. | `geo_type` (required)<br>`geo_value` (required) | [`?geo_type=state&geo_value=pa`](https://delphi.cmu.edu/epidata/v5/metadata/geo_signals/?geo_type=state&geo_value=pa) |
+| [`report_times/`](https://delphi.cmu.edu/epidata/v5/metadata/report_times/) | Sorted list of publication dates (`report_time`). | `source` (required)<br>`signal` (optional) | [`?source=nssp`](https://delphi.cmu.edu/epidata/v5/metadata/report_times/?source=nssp) |
+| [`reference_times/`](https://delphi.cmu.edu/epidata/v5/metadata/reference_times/) | Sorted list of observation dates (`reference_time`). | `source` (required)<br>`signal` (optional) | [`?source=nssp`](https://delphi.cmu.edu/epidata/v5/metadata/reference_times/?source=nssp) |
+| [`extra_key_values/`](https://delphi.cmu.edu/epidata/v5/metadata/extra_key_values/) | Distinct values for source-specific extra dimension columns. | `source` (required)<br>`signal` (optional) | [`?source=nwss`](https://delphi.cmu.edu/epidata/v5/metadata/extra_key_values/?source=nwss) |
+| [`aux_schema/`](https://delphi.cmu.edu/epidata/v5/metadata/aux_schema/) | Column names and SQL data types for auxiliary tables. | `source` (optional) | [`?source=nwss`](https://delphi.cmu.edu/epidata/v5/metadata/aux_schema/?source=nwss) |
+| [`api_version_hash/`](https://delphi.cmu.edu/epidata/v5/metadata/api_version_hash/) | Current Git commit hash of the running API server. | None | [`api_version_hash/`](https://delphi.cmu.edu/epidata/v5/metadata/api_version_hash/) |
+
diff --git a/docs/api/v5_migration.md b/docs/api/v5_migration.md
@@ -0,0 +1,98 @@
+---
+title: V4 to V5 Migration Guide
+parent: Delphi V5 API
+nav_order: 4
+---
+
+# V4 to V5 Migration Guide
+
+The legacy Epidata V4 API, including the [main endpoint](covidcast.md) and [other historical endpoints](README.md), is transitioning to the [V5 API](v5.md). This transition is occurring source by source. All V4 sources will continue to operate until the migration is complete (tentatively scheduled for October 2026), and endpoints that are no longer updated will remain accessible on V4. For new integrations, start directly on V5 and fall back to V4 only for sources that are not yet supported.
+
+## Endpoint mapping
+
+The single `covidcast` endpoint splits into several purpose-built V5 routes determined by query type. The "other endpoints" column highlights examples (`fluview`, `flusurv`, `wiki`) to illustrate differences across endpoints. Refer to each endpoint's documentation for specific behavior:
+
+| Task | V4 (`covidcast`) | V4 (Other Endpoints) | V5 Equivalent |
+| :--- | :--- | :--- | :--- |
+| Fetch latest data or snapshot as of a past date | `covidcast` (default query or with `as_of`) | Endpoint-specific (`fluview` has no `as_of`) | [`/epidata/v5/snapshot/`](v5_api_queries.md#snapshot-parameters) |
+| Fetch full revision history for a signal | `covidcast` with `issues` | Supported by some (`fluview`, `flusurv` with `issues`) | [`/epidata/v5/archive/`](v5_api_queries.md#archive-parameters) |
+| Discover sources, signals, geo types, and date ranges | [`covidcast_meta`](covidcast_meta.md) | Shared [`meta`](01meta.md) for some `fluview` | [`/epidata/v5/metadata/`](v5_api_queries.md#metadata) |
+| Access source-specific auxiliary tables | None | None | [`/epidata/v5/aux_data/`](v5_api_queries.md#auxiliary-data-parameters) |
+| Filter by publication lag | `covidcast` with `lag` | Supported by some (`fluview`, `flusurv`) | None (compute `report_time - reference_time`) |
+
+## Parameter changes
+
+Most `covidcast` query parameters carry over to V5 with the same name, but some have been renamed, dropped, or added. Historical endpoints do not share parameter names with `covidcast`. Parameters for `fluview` are shown below as an example, but consult each endpoint's documentation for details:
+
+| V4 Parameter (`covidcast`) | V4 (Other Endpoints, e.g. `fluview`) | V5 Equivalent | Notes |
+| :--- | :--- | :--- | :--- |
+| `data_source` | `endpoint` | `source` | Identifies the source dataset in V5 (replaces V4 `data_source` and endpoint names). |
+| `signal` | none | `signal` | Identifies the specific signal name within the source. |
+| `geo_type` | not exposed (`fluview` supports only `regions`) | `geo_type` | Specifies geographic resolution (e.g., `state`, `county`). |
+| `geo_value` | `regions` for `fluview` | none | Removed in V5. Both `/snapshot/` and `/archive/` return all locations for the requested `geo_type`. Filter locations client-side. |
+| `time_type` | not exposed (`fluview` is always `epiweeks`) | none | Removed in V5. All V5 endpoints use standard calendar dates (`reference_time`). |
+| `time_values` | `epiweeks` for `fluview` | none | Removed in V5 queries. Fetch the full signal and filter by `reference_time` client-side. |
+| `as_of` | none (`fluview` has no `as_of`) | `snapshot_date` | In V5, used only in `/snapshot/` to fetch data known as of a past date. Omit to return the latest data. |
+| `issues` | `issues` (where supported) | `report_time_query` | In V5, used only in `/archive/`. Accepts a single date or comparison filter (e.g. `<2025-10-16>`). |
+| `lag` | `lag` (where supported) | none | Removed in V5. Compute client-side as `report_time - reference_time`. |
+| none | none | `fill_method` | New in V5. Selects the imputation method when aggregating sub-geographies (`source`, `fill_ave`, or `fill_zero`). See [Imputation](v5_api_queries.md#imputation-fill-methods). |
+| none | none | `extra_keys` | New in V5. Filters on source-specific dimensions (such as `age_group:18-49`). |
+
+## Response field changes
+
+Response fields follow a similar pattern. In the table below, `fluview` serves as an example of an endpoint with custom fields. Field names vary by V4 endpoint (for example, `wiki` returns `article`, `count`, and `hour`):
+
+| V4 Field (`covidcast`) | V4 (Other Endpoints, e.g. `fluview`) | V5 Field | Notes |
+| :--- | :--- | :--- | :--- |
+| `source` | not returned (identified by endpoint name) | dropped | Omitted in V5 responses because the source is already specified in the request. |
+| `signal` | none (implicit from endpoint) | `signal` | Identifies the signal name in V5. |
+| `value` | Endpoint-specific columns (e.g. `num_ili`, `wili`, `ili`) | `value` | Standardized metric value column across all V5 sources. |
+| not returned (implicit from query) | not returned (implicit from endpoint) | `geo_type` | Explicitly included in V5 responses to identify geographic resolution. |
+| `geo_value` | `region` for `fluview` | `geo_value` | Standardized location identifier across all V5 responses. |
+| `time_value` | `epiweek` for `fluview` | `reference_time` | Standardized date in `YYYY-MM-DD` format representing the observation period. |
+| `issue` | `issue` (where returned) | `report_time` | Standardized date in `YYYY-MM-DD` format representing when the data point was published (returned in `/archive/`). |
+| `lag` | `lag` (where returned) | dropped | Omitted in V5 responses. Calculate client-side as `report_time - reference_time`. |
+| `direction` | none | dropped | Deprecated in V4 and removed in V5. |
+| `stderr`, `sample_size` | none | `ci_lower`, `ci_upper` | Expresses uncertainty as explicit confidence interval bounds on `value` when provided by the data source. |
+| `missing_value`, `missing_stderr`, `missing_sample_size` | none | dropped | Replaced in V5 by `fill_method` variants and standard null values in `value`. |
+| none | none | `fill_method` | Indicates which null-handling imputation method was applied (`source`, `fill_ave`, or `fill_zero`). |
+
+Some sources also include extra columns, such as `age_group` for pophive and `nwss_source`, `sample_index`, and `pcr_target` for nwss.
+
+## A query, before and after
+
+Here is the same request fetching NHSN COVID admissions as known on 2024-12-07 for every state in both APIs:
+
+V4:
+
+```url
+https://api.delphi.cmu.edu/epidata/covidcast/?data_source=nhsn&signal=confirmed_admissions_covid_ew&time_type=week&geo_type=state&geo_value=*&as_of=20241207
+```
+
+V5:
+
+```url
+https://delphi.cmu.edu/epidata/v5/snapshot/?source=nhsn&signal=confirmed_admissions_covid_ew&geo_type=state&snapshot_date=2024-12-07
+```
+
+The V5 query omits `geo_value=*` because it always returns all locations for the requested `geo_type`. You can filter down to specific locations client-side after downloading.
+
+## Revision history queries
+
+Where you previously passed `issues` to `covidcast`, use [`/epidata/v5/archive/`](v5_api_queries.md#archive-parameters) with `report_time_query` instead:
+
+```url
+https://delphi.cmu.edu/epidata/v5/archive/?source=nssp&signal=pct_ed_visits_influenza&geo_type=state&report_time_query=<2025-10-16
+```
+
+## Updating your client
+
+Both [`epidatr`](https://cmu-delphi.github.io/epidatr/) (R) and [`epidatpy`](https://cmu-delphi.github.io/epidatpy/) (Python) natively support V5 queries.
+
+- **R users**. Update to the latest `epidatr` release and consult the [`epidatr` migration guide](https://cmu-delphi.github.io/epidatr/articles/migration-guide.html) for function mappings.
+- **Python users**. Migrate to `epidatpy` using the [`epidatpy` migration guide](https://cmu-delphi.github.io/epidatpy/migration-guide.html). The legacy Python client (see [Client Libraries](client_libraries.md)) only supports V4 and will not receive V5 updates.
+
+## Checking whether a source has moved
+
+Query [`/epidata/v5/metadata/?source=<name>`](v5_meta.md) to check whether a source is available in V5. It returns available signals, geo types, and date ranges for `reference_time` and `report_time`. The `report_times` and `reference_times` sub-endpoints list full date histories when needed. New sources are announced on the [Delphi mailing list](https://lists.andrew.cmu.edu/mailman/listinfo/delphi-covidcast-api) as they are migrated.
+
diff --git a/docs/api/v5_signals.md b/docs/api/v5_signals.md
@@ -7,8 +7,26 @@ has_children: true
 
 # Delphi V5 Sources and Signals
 
+> **The legacy V4 API is being phased out.** See the [V4 to V5 Migration Guide](v5_migration.md) for guidance on migrating existing queries.
+{: .warning }
 
-### National Syndromic Surveillance Program ED Visits ([`nssp`](v5-signals/nssp.md))
+## V4 to V5 Source Coverage
+
+Not all V4 sources have migrated to V5. The table below lists available V5 sources as of August 25, 2026:
+
+| V4 Source | V5 Source |
+| :--- | :--- |
+| `nssp` | `nssp` |
+| `nhsn` | `nhsn` |
+| `doctor-visits` | `claims_data_outpatient` |
+| `hospital-admissions` | `claims_data_inpatient` |
+| None (new in V5) | [`pophive`](v5-signals/epic-cosmos.md), [`nwss`](v5-signals/nwss.md), [`va_respiratory`](v5-signals/va_respiratory.md) |
+
+All other sources remain V4-only. Because this documentation is updated periodically, query the [`/epidata/v5/metadata/`](v5_meta.md) endpoint (e.g. `https://delphi.cmu.edu/epidata/v5/metadata/`) to check live source availability in V5.
+
+---
+
+### National Syndromic Surveillance Program ED Visits (`nssp`)
 
 | Attribute | Details |
 | :--- | :--- |
@@ -20,7 +38,7 @@ Weekly percentage of emergency department visits associated with respiratory pat
 
 ---
 
-### NHSN Respiratory Hospitalizations ([`nhsn`](v5-signals/nhsn.md))
+### NHSN Respiratory Hospitalizations (`nhsn`)
 
 | Attribute | Details |
 | :--- | :--- |
@@ -55,7 +73,7 @@ Daily ED visit counts and percentages from Epic Cosmos, stratified by pathogen.
 
 ---
 
-### Outpatient Claims ([`claims_data_outpatient`](v5-signals/claims_data_outpatient.md))
+### Outpatient Claims (`claims_data_outpatient`)
 
 | Attribute | Details |
 | :--- | :--- |
@@ -66,7 +84,7 @@ Daily ED visit counts and percentages from Epic Cosmos, stratified by pathogen.
 Daily outpatient visit percentages derived from medical billing claims.
 ---
 
-### Inpatient Claims ([`claims_data_inpatient`](v5-signals/claims_data_inpatient.md))
+### Inpatient Claims (`claims_data_inpatient`)
 
 | Attribute | Details |
 | :--- | :--- |