Search and query CDC public health data — mortality, vaccinations, surveillance, behavioral risk.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Search the CDC dataset catalog by keyword, category, or tag. Returns IDs, names, truncated descriptions, asset types, column counts, and update timestamps. The catalog also holds charts, maps, stories, files, and links; an entry whose columnCount is 0 is one of those and yields no data from the other tools. Use cdc_get_dataset_schema for the full column list of a chosen dataset.
Filter by domain tags (e.g., ["covid19", "surveillance"]). Tags widen the search instead of narrowing it — a dataset matches when it carries any one of them, so every tag added returns more results, and an unrecognized tag matches nothing and leaves the result set unchanged. Values match the catalog's own tag vocabulary, case-insensitively; call cdc_list_catalog_vocabulary for the values in use with their entry counts, or read the tags field on any result. To narrow, combine tags with query or category, which intersect with the tag set.
Results to return (default 10). One call returns at most 100: a larger limit, up to 10,000, is capped at 100, and the response says so and gives the offset to continue from while more datasets match. offset plus limit must not exceed 10000 once limit is capped.
Result ordering. "dataset_id" (default) sorts deterministically by each dataset's unique catalog ID — required for stable offset pagination, since consecutive pages form a gap-free, duplicate-free traversal. "relevance" returns best-match ranking for keyword search but is not stably paginable across pages, so walking offsets can skip or repeat datasets.
Full-text search across dataset names and descriptions (e.g., "diabetes mortality", "lead exposure children").
CDC Socrata host to search. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog and return the same entries, so switching hosts neither widens nor narrows a search — chronic-disease and small-area collections such as PLACES, the Heart Disease & Stroke Atlas, and Environmental Public Health Tracking are found from either.
Pagination offset for browsing beyond first page (max 9999). offset plus limit must not exceed 10000 once limit is capped; both CDC portals hold well under two thousand entries, so offsets near that ceiling page past the end of the catalog.
Filter by domain category (e.g., "NNDSS", "Vaccinations", "Behavioral Risk Factors"). Values come from the catalog's own vocabulary and are matched exactly, including case — "Vaccinations" matches 89 entries while "Vaccination" matches none. Call cdc_list_catalog_vocabulary for every value with its entry count rather than guessing at one.
Search the CDC dataset catalog by keyword, category, or tag. Returns IDs, names, truncated descriptions, asset types, column counts, and update timestamps. The catalog also holds charts, maps, stories, files, and links; an entry whose columnCount is 0 is one of those and yields no data from the other tools. Use cdc_get_dataset_schema for the full column list of a chosen dataset.
| Argument | Type | Description |
|---|---|---|
| tags | array | Filter by domain tags (e.g., ["covid19", "surveillance"]). Tags widen the search instead of narrowing it — a dataset matches when it carries any one of them, so every tag added returns more results, and an unrecognized tag matches nothing and leaves the result set unchanged. Values match the catalog's own tag vocabulary, case-insensitively; call cdc_list_catalog_vocabulary for the values in use with their entry counts, or read the tags field on any result. To narrow, combine tags with query or category, which intersect with the tag set. |
| limit | integer | Results to return (default 10). One call returns at most 100: a larger limit, up to 10,000, is capped at 100, and the response says so and gives the offset to continue from while more datasets match. offset plus limit must not exceed 10000 once limit is capped. |
| order | string | Result ordering. "dataset_id" (default) sorts deterministically by each dataset's unique catalog ID — required for stable offset pagination, since consecutive pages form a gap-free, duplicate-free traversal. "relevance" returns best-match ranking for keyword search but is not stably paginable across pages, so walking offsets can skip or repeat datasets. |
| query | string | Full-text search across dataset names and descriptions (e.g., "diabetes mortality", "lead exposure children"). |
| domain | string | CDC Socrata host to search. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog and return the same entries, so switching hosts neither widens nor narrows a search — chronic-disease and small-area collections such as PLACES, the Heart Disease & Stroke Atlas, and Environmental Public Health Tracking are found from either. |
| offset | integer | Pagination offset for browsing beyond first page (max 9999). offset plus limit must not exceed 10000 once limit is capped; both CDC portals hold well under two thousand entries, so offsets near that ceiling page past the end of the catalog. |
| category | string | Filter by domain category (e.g., "NNDSS", "Vaccinations", "Behavioral Risk Factors"). Values come from the catalog's own vocabulary and are matched exactly, including case — "Vaccinations" matches 89 entries while "Vaccination" matches none. Call cdc_list_catalog_vocabulary for every value with its entry count rather than guessing at one. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"description": "Tag value"
},
"description": "Filter by domain tags (e.g., [\"covid19\", \"surveillance\"]). Tags widen the search instead of narrowing it — a dataset matches when it carries any one of them, so every tag added returns more results, and an unrecognized tag matches nothing and leaves the result set unchanged. Values match the catalog's own tag vocabulary, case-insensitively; call cdc_list_catalog_vocabulary for the values in use with their entry counts, or read the tags field on any result. To narrow, combine tags with query or category, which intersect with the tag set."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 10000,
"minimum": 1,
"description": "Results to return (default 10). One call returns at most 100: a larger limit, up to 10,000, is capped at 100, and the response says so and gives the offset to continue from while more datasets match. offset plus limit must not exceed 10000 once limit is capped."
},
"order": {
"enum": [
"dataset_id",
"relevance"
],
"type": "string",
"default": "dataset_id",
"description": "Result ordering. \"dataset_id\" (default) sorts deterministically by each dataset's unique catalog ID — required for stable offset pagination, since consecutive pages form a gap-free, duplicate-free traversal. \"relevance\" returns best-match ranking for keyword search but is not stably paginable across pages, so walking offsets can skip or repeat datasets."
},
"query": {
"type": "string",
"description": "Full-text search across dataset names and descriptions (e.g., \"diabetes mortality\", \"lead exposure children\")."
},
"domain": {
"enum": [
"data.cdc.gov",
"chronicdata.cdc.gov"
],
"type": "string",
"default": "data.cdc.gov",
"description": "CDC Socrata host to search. \"data.cdc.gov\" (default) and \"chronicdata.cdc.gov\" front the same catalog and return the same entries, so switching hosts neither widens nor narrows a search — chronic-disease and small-area collections such as PLACES, the Heart Disease & Stroke Atlas, and Environmental Public Health Tracking are found from either."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9999,
"minimum": 0,
"description": "Pagination offset for browsing beyond first page (max 9999). offset plus limit must not exceed 10000 once limit is capped; both CDC portals hold well under two thousand entries, so offsets near that ceiling page past the end of the catalog."
},
"category": {
"type": "string",
"description": "Filter by domain category (e.g., \"NNDSS\", \"Vaccinations\", \"Behavioral Risk Factors\"). Values come from the catalog's own vocabulary and are matched exactly, including case — \"Vaccinations\" matches 89 entries while \"Vaccination\" matches none. Call cdc_list_catalog_vocabulary for every value with its entry count rather than guessing at one."
}
},
"additionalProperties": false
}Fetch the column schema for a CDC dataset — names, data types, descriptions, row count, and last-updated timestamp. Returns the first 100 columns by default; wide datasets continue via column_offset. The dataset description is capped at 4,000 characters by default; pass full_description: true for the whole text. Get dataset IDs from cdc_discover_datasets.
| Argument | Type | Description |
|---|---|---|
| domain | string | CDC Socrata host to fetch the dataset from. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog, so a four-by-four ID resolves on either and the default works whichever host the dataset was found on. |
| datasetId* | string | Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets. |
| column_limit | integer | Columns to return in this call (default 100). Every dataset under the default arrives whole; past it the response reports totalCount and a nextOffset to pass back as column_offset. Raise this to pull a wide schema in one call — a value at or above the column count returns every column. |
| column_offset | integer | Index of the first column to return, for continuing past a previous call (default 0). Columns keep the order the dataset declares, so column_offset plus column_limit walks the schema without gaps or repeats. An offset at or past the column count returns an empty window rather than an error. |
| full_description | boolean |
List the controlled vocabularies cdc_discover_datasets' category and tags filters are matched against — every domain category and domain tag the CDC catalog publishes, each with the number of entries carrying it. Call it before filtering a search: a value the catalog does not carry matches nothing and returns an empty page, which is indistinguishable from a real value with no results. All categories come back whole; the tag vocabulary runs to roughly 1,600 values, so tags are ranked by entry count and returned one page at a time via tag_limit and tag_offset. Pass filter to narrow both vocabularies to the values whose words contain it.
| Argument | Type | Description |
|---|---|---|
| domain | string | CDC Socrata host to read the vocabulary from. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog and publish the same vocabulary, so this selects which host answers, never which values exist. |
| filter | string | Narrow both vocabularies to the values related to this text. A value matches when every word of the filter appears inside one of its words ("vaccin" reaches "Vaccinations" and "covid-19 vaccination"), or when the whole value appears in the filter. Matching is not fuzzy — a misspelling returns nothing rather than a guess — and a filter under three letters is ignored. |
| tag_limit | integer | Tags to return in this call (default 50). Tags are ranked by entry count, so the default page is the most-used end of the vocabulary; the response reports how many matched and a nextOffset while more remain. A tag_limit at or above the number of matching tags returns all of them in one call. Categories are never paged — every one arrives whole. |
Execute a SoQL query against any CDC dataset. Supports filtering, aggregation, sorting, full-text search, and field selection. Use cdc_discover_datasets to find dataset IDs and cdc_get_dataset_schema to inspect columns before querying.
| Argument | Type | Description |
|---|---|---|
| group | string | SoQL GROUP BY clause. Requires aggregate functions in select. |
| limit | integer | Max rows to return (default 100). One call returns at most 5,000 rows: a larger limit, up to 1,000,000, is capped at 5,000, and the response says so and gives a nextOffset when more rows remain. Fewer come back when the page would carry the response past its 200,000-character budget, counted over the whole result — the rows as JSON and as the rendered table together; the response says so and gives a nextOffset to resume from. |
| order | string | SoQL ORDER BY clause. Field name with optional ASC/DESC: "total_deaths DESC". Set one from the first page whenever paging with offset, and keep it for the whole walk: SODA does not order results implicitly, so consecutive offsets without a deterministic order, or under a changed one, can skip or repeat rows. End it with a tie-breaker unique to each row: on ungrouped rows, the system field `:id`, present on every dataset (order="year DESC, :id"); on a grouped query, the grouped columns (order="total DESC, state"); on a distinct select, the selected columns. Socrata rejects `:id` once rows are grouped. |
| where | string | SoQL WHERE clause. Strings must be single-quoted: "state='California' AND year=2020". If a column name matches a SoQL keyword (group, select, where, order, limit, offset, having, search), wrap it in backticks: "`group`='By Year'". |
Query CDC WONDER for national US mortality statistics — deaths, population, and crude/age-adjusted death rates — across its five mortality databases, selected with the database input: final underlying-cause data for 1999–2020 (the default) or 2018–2024, provisional data running from 2018 through the current year, and two multiple-cause databases covering the same two eras. Break results out by year, age group, sex, and/or race, and filter by ICD-10 cause of death, sex, age group, or year range; on a multiple-cause database, mcd_icd10 additionally matches a cause listed anywhere on the death certificate rather than only the one certified as underlying. Each database holds a different span of years (1999–2026 across all of them) and a request whose year_range falls outside the selected one's span is rejected with that span named. WONDER is a separate CDC system from the Socrata datasets the other cdc_* tools query. Data is national only — sub-national (state/county) breakdowns are not available through the API (CDC vital-statistics policy). Cause of death is a filter, not a grouping. Some measure cells come back as a CDC status token rather than a number — "Suppressed" (withheld for confidentiality), "Unreliable" (a rate from fewer than 20 deaths), or "Not Applicable" (no population denominator); those cells read null in rows and each one is listed in cellNotes with its token. CDC also drops whole rows before sending the table — strata with zero deaths, and strata whose death count is suppressed — so a stratum can be missing from rows entirely; messages carries CDC's statement whenever that happened. Each response is bounded by a 200,000-character budget counted over the whole result, so a broad grouping — one can run past two thousand rows — comes back a page at a time: the response reports the table's totalCount and a nextOffset to continue from, and limit takes smaller pages. Paging shapes the response only — WONDER is asked once either way, and the figures, caveats and hidden-row notices are the same on every page. CDC rejects requests made less than 15 seconds apart across all five databases, so calls are spaced automatically: calls made while another is running wait their turn and run one after another, each queued call adding about 16 seconds plus its own query time before it returns.
| Argument | Type |
|---|
| Return the dataset description whole (default false). By default a description longer than 4,000 characters is cut there, and the response sets descriptionTruncated and descriptionLength. Column descriptions are never shortened either way. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"datasetId"
],
"properties": {
"domain": {
"enum": [
"data.cdc.gov",
"chronicdata.cdc.gov"
],
"type": "string",
"default": "data.cdc.gov",
"description": "CDC Socrata host to fetch the dataset from. \"data.cdc.gov\" (default) and \"chronicdata.cdc.gov\" front the same catalog, so a four-by-four ID resolves on either and the default works whichever host the dataset was found on."
},
"datasetId": {
"type": "string",
"pattern": "^[a-z0-9]{4}-[a-z0-9]{4}$",
"description": "Four-by-four dataset identifier (e.g., \"bi63-dtpu\"). Obtain from cdc_discover_datasets."
},
"column_limit": {
"type": "integer",
"default": 100,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Columns to return in this call (default 100). Every dataset under the default arrives whole; past it the response reports totalCount and a nextOffset to pass back as column_offset. Raise this to pull a wide schema in one call — a value at or above the column count returns every column."
},
"column_offset": {
"type": "integer",
"default": 0,
"maximum": 10000,
"minimum": 0,
"description": "Index of the first column to return, for continuing past a previous call (default 0). Columns keep the order the dataset declares, so column_offset plus column_limit walks the schema without gaps or repeats. An offset at or past the column count returns an empty window rather than an error."
},
"full_description": {
"type": "boolean",
"default": false,
"description": "Return the dataset description whole (default false). By default a description longer than 4,000 characters is cut there, and the response sets descriptionTruncated and descriptionLength. Column descriptions are never shortened either way."
}
},
"additionalProperties": false
}| tag_offset |
| integer |
| Index of the first tag to return, for continuing past a previous call (default 0). Ranking is stable, so tag_offset plus tag_limit walks the vocabulary without gaps or repeats. An offset at or past the number of matching tags returns an empty tag list rather than an error. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"domain": {
"enum": [
"data.cdc.gov",
"chronicdata.cdc.gov"
],
"type": "string",
"default": "data.cdc.gov",
"description": "CDC Socrata host to read the vocabulary from. \"data.cdc.gov\" (default) and \"chronicdata.cdc.gov\" front the same catalog and publish the same vocabulary, so this selects which host answers, never which values exist."
},
"filter": {
"type": "string",
"description": "Narrow both vocabularies to the values related to this text. A value matches when every word of the filter appears inside one of its words (\"vaccin\" reaches \"Vaccinations\" and \"covid-19 vaccination\"), or when the whole value appears in the filter. Matching is not fuzzy — a misspelling returns nothing rather than a guess — and a filter under three letters is ignored."
},
"tag_limit": {
"type": "integer",
"default": 50,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Tags to return in this call (default 50). Tags are ranked by entry count, so the default page is the most-used end of the vocabulary; the response reports how many matched and a nextOffset while more remain. A tag_limit at or above the number of matching tags returns all of them in one call. Categories are never paged — every one arrives whole."
},
"tag_offset": {
"type": "integer",
"default": 0,
"maximum": 10000,
"minimum": 0,
"description": "Index of the first tag to return, for continuing past a previous call (default 0). Ranking is stable, so tag_offset plus tag_limit walks the vocabulary without gaps or repeats. An offset at or past the number of matching tags returns an empty tag list rather than an error."
}
},
"additionalProperties": false
}| domain | string | CDC Socrata host to query. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog, so a four-by-four ID returns the same rows from either and the default works whichever host the dataset was found on. |
| having | string | SoQL HAVING clause. Filters aggregated results. |
| offset | integer | Row offset for pagination (max 1,000,000). Pair with a deterministic order clause — an offset walk over unordered results can skip or repeat rows. |
| search | string | Full-text search across all text columns. For precise filtering use the where parameter instead. |
| select | string | SoQL SELECT clause — column names, aliases, or aggregates: "state, sum(deaths) as total_deaths". Omit for all columns. To enumerate distinct values of a column, set select to "{column}, count(*) as count" with group="{column}" and order="count DESC, {column}". |
| datasetId* | string | Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"datasetId"
],
"properties": {
"group": {
"type": "string",
"description": "SoQL GROUP BY clause. Requires aggregate functions in select."
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 1000000,
"minimum": 1,
"description": "Max rows to return (default 100). One call returns at most 5,000 rows: a larger limit, up to 1,000,000, is capped at 5,000, and the response says so and gives a nextOffset when more rows remain. Fewer come back when the page would carry the response past its 200,000-character budget, counted over the whole result — the rows as JSON and as the rendered table together; the response says so and gives a nextOffset to resume from."
},
"order": {
"type": "string",
"description": "SoQL ORDER BY clause. Field name with optional ASC/DESC: \"total_deaths DESC\". Set one from the first page whenever paging with offset, and keep it for the whole walk: SODA does not order results implicitly, so consecutive offsets without a deterministic order, or under a changed one, can skip or repeat rows. End it with a tie-breaker unique to each row: on ungrouped rows, the system field `:id`, present on every dataset (order=\"year DESC, :id\"); on a grouped query, the grouped columns (order=\"total DESC, state\"); on a distinct select, the selected columns. Socrata rejects `:id` once rows are grouped."
},
"where": {
"type": "string",
"description": "SoQL WHERE clause. Strings must be single-quoted: \"state='California' AND year=2020\". If a column name matches a SoQL keyword (group, select, where, order, limit, offset, having, search), wrap it in backticks: \"`group`='By Year'\"."
},
"domain": {
"enum": [
"data.cdc.gov",
"chronicdata.cdc.gov"
],
"type": "string",
"default": "data.cdc.gov",
"description": "CDC Socrata host to query. \"data.cdc.gov\" (default) and \"chronicdata.cdc.gov\" front the same catalog, so a four-by-four ID returns the same rows from either and the default works whichever host the dataset was found on."
},
"having": {
"type": "string",
"description": "SoQL HAVING clause. Filters aggregated results."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 1000000,
"minimum": 0,
"description": "Row offset for pagination (max 1,000,000). Pair with a deterministic order clause — an offset walk over unordered results can skip or repeat rows."
},
"search": {
"type": "string",
"description": "Full-text search across all text columns. For precise filtering use the where parameter instead."
},
"select": {
"type": "string",
"description": "SoQL SELECT clause — column names, aliases, or aggregates: \"state, sum(deaths) as total_deaths\". Omit for all columns. To enumerate distinct values of a column, set select to \"{column}, count(*) as count\" with group=\"{column}\" and order=\"count DESC, {column}\"."
},
"datasetId": {
"type": "string",
"pattern": "^[a-z0-9]{4}-[a-z0-9]{4}$",
"description": "Four-by-four dataset identifier (e.g., \"bi63-dtpu\"). Obtain from cdc_discover_datasets."
}
},
"additionalProperties": false
}| Description |
|---|
| sex | string | Filter by sex. |
| limit | integer | Rows to return from the table CDC sent — any positive integer. Omit to take as many as fit. Either way fewer come back when the page would carry the response past its 200,000-character budget, counted over the whole result — the rows, their cell notes, and the caveats and messages, as JSON and as the rendered table together; the response says so and gives a nextOffset to resume from. WONDER's request carries no limit of its own, so this pages a table already fetched in full rather than narrowing the query: the deaths, rates, caveats and hidden-row notices are the same whichever page is read. |
| offset | integer | Index of the first row to return, for continuing past a previous call (default 0, max 10,000). Rows keep the order CDC returned them in, which is stable for a given query, so offset plus limit walks the table without gaps or repeats. An offset at or past the row total returns an empty page rather than an error. |
| database | string | Which WONDER mortality database to query. "underlying_1999_2020" (D76) is final data for 1999–2020 and the default. "provisional" (D176) runs 2018 through the current year, updated weekly, and returns the most recent years labelled e.g. "2025 (provisional)". "underlying_2018_2024" (D158) is settled — not provisional — data for 2018–2024. "multiple_1999_2020" (D77) and "multiple_2018_2024" (D157) record every cause listed on the death certificate; without an mcd_icd10 filter they return the same figures as the underlying-cause database for the same era, so pick one only to use that filter. The two 1999–2020 databases report race in CDC's four bridged groups; the other three use the six single-race groups — figures broken out by race are not comparable between the two families. |
| group_by | array | Dimensions to break results out by (1–4, each at most once), in output-column order — e.g. ["year"], ["year","sex"], ["age_group","race"]. Results are always national. Cause of death is a filter (cause_icd10), not a grouping. "race" resolves to whichever race vocabulary the selected database uses — four bridged groups (Asian and Pacific Islander combined) on the 1999–2020 databases, six single-race categories on the others, one of them "More than one race" — so a race series from one family cannot be spliced onto one from the other. |
| mcd_icd10 | any | Filter to deaths with any of these ICD-10 codes recorded anywhere on the death certificate, whether or not it was the underlying cause — e.g. "died with a respiratory condition listed", a population no underlying-cause query can produce. Takes one code or range, or a list of them, e.g. opioid involvement as ["T40.0","T40.1","T40.2","T40.3","T40.4","T40.6"]. Valid only when database is "multiple_1999_2020", "multiple_2018_2024", or "provisional"; the other databases record only the underlying cause and reject it. "999--999", the withheld-cause marker described under cause_icd10, is offered here too but only by "provisional". Combines with cause_icd10, which keeps meaning the underlying cause: a death must match both filters. Omit for all causes. |
| age_groups | array | Restrict to deaths in any of the listed age groups — e.g. ["25-34","35-44"] covers both; a repeated group counts once. "1" is the under-1-year group. "NS" is the group CDC puts a death in when the age was not recorded; it is not covered by any of the ten-year groups, so a filter listing all eleven of those still leaves those deaths out and returns fewer deaths than the same query unfiltered. CDC refuses "NS" beside only some of the other groups: list it on its own to count those deaths, or list all twelve values — the same as omitting age_groups — to include them. Omit for all ages, which includes them. |
| year_range | object | Inclusive year range; from must not be later than to. These bounds span every database (1999–2026); the years the selected one actually holds are narrower, and a range outside them is rejected with that database's span named. Omit for all years the database holds. |
| cause_icd10 | any | Filter to ICD-10 underlying causes of death — the single condition CDC certified as having started the chain of events leading to death. Takes one code or range, or a list of them for a cause defined as a code set, e.g. drug overdose as ["X40","X41","X42","X43","X44","X60","X61","X62","X63","X64","X85","Y10","Y11","Y12","Y13","Y14"]. Omit for all causes. Accepted by every database. "999--999" is not an ICD-10 code but CDC's own marker for deaths whose cause it is still withholding under the provisional database's six-month reporting lag; it counts that backlog, and only the "provisional" database offers it. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"sex": {
"enum": [
"all",
"male",
"female"
],
"type": "string",
"default": "all",
"description": "Filter by sex."
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows to return from the table CDC sent — any positive integer. Omit to take as many as fit. Either way fewer come back when the page would carry the response past its 200,000-character budget, counted over the whole result — the rows, their cell notes, and the caveats and messages, as JSON and as the rendered table together; the response says so and gives a nextOffset to resume from. WONDER's request carries no limit of its own, so this pages a table already fetched in full rather than narrowing the query: the deaths, rates, caveats and hidden-row notices are the same whichever page is read."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 10000,
"minimum": 0,
"description": "Index of the first row to return, for continuing past a previous call (default 0, max 10,000). Rows keep the order CDC returned them in, which is stable for a given query, so offset plus limit walks the table without gaps or repeats. An offset at or past the row total returns an empty page rather than an error."
},
"database": {
"enum": [
"underlying_1999_2020",
"provisional",
"underlying_2018_2024",
"multiple_1999_2020",
"multiple_2018_2024"
],
"type": "string",
"default": "underlying_1999_2020",
"description": "Which WONDER mortality database to query. \"underlying_1999_2020\" (D76) is final data for 1999–2020 and the default. \"provisional\" (D176) runs 2018 through the current year, updated weekly, and returns the most recent years labelled e.g. \"2025 (provisional)\". \"underlying_2018_2024\" (D158) is settled — not provisional — data for 2018–2024. \"multiple_1999_2020\" (D77) and \"multiple_2018_2024\" (D157) record every cause listed on the death certificate; without an mcd_icd10 filter they return the same figures as the underlying-cause database for the same era, so pick one only to use that filter. The two 1999–2020 databases report race in CDC's four bridged groups; the other three use the six single-race groups — figures broken out by race are not comparable between the two families."
},
"group_by": {
"type": "array",
"items": {
"enum": [
"year",
"age_group",
"sex",
"race"
],
"type": "string"
},
"default": [
"year"
],
"maxItems": 4,
"minItems": 1,
"description": "Dimensions to break results out by (1–4, each at most once), in output-column order — e.g. [\"year\"], [\"year\",\"sex\"], [\"age_group\",\"race\"]. Results are always national. Cause of death is a filter (cause_icd10), not a grouping. \"race\" resolves to whichever race vocabulary the selected database uses — four bridged groups (Asian and Pacific Islander combined) on the 1999–2020 databases, six single-race categories on the others, one of them \"More than one race\" — so a race series from one family cannot be spliced onto one from the other."
},
"mcd_icd10": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"const": "999--999"
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 code or range, same form as cause_icd10 — a chapter such as \"S00-T98\" (injury and poisoning, a chapter the underlying-cause finder does not list), a block such as \"J09-J18\" (influenza and pneumonia), or a single code such as \"T40.1\" (heroin)."
},
{
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"const": "999--999"
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 code or range, same form as cause_icd10 — a chapter such as \"S00-T98\" (injury and poisoning, a chapter the underlying-cause finder does not list), a block such as \"J09-J18\" (influenza and pneumonia), or a single code such as \"T40.1\" (heroin)."
}
],
"description": "One list entry: an ICD-10 code or range, or the withheld-cause marker."
},
"maxItems": 50,
"description": "A list of up to 50 entries, each in the single-value form, matched as a union: a death counts once when it matches any of them, so a code set such as X40–X44 plus X60–X64 is one series with one set of rates. Repeated entries are ignored. An empty list reads as omitted."
}
],
"description": "Filter to deaths with any of these ICD-10 codes recorded anywhere on the death certificate, whether or not it was the underlying cause — e.g. \"died with a respiratory condition listed\", a population no underlying-cause query can produce. Takes one code or range, or a list of them, e.g. opioid involvement as [\"T40.0\",\"T40.1\",\"T40.2\",\"T40.3\",\"T40.4\",\"T40.6\"]. Valid only when database is \"multiple_1999_2020\", \"multiple_2018_2024\", or \"provisional\"; the other databases record only the underlying cause and reject it. \"999--999\", the withheld-cause marker described under cause_icd10, is offered here too but only by \"provisional\". Combines with cause_icd10, which keeps meaning the underlying cause: a death must match both filters. Omit for all causes."
},
"age_groups": {
"type": "array",
"items": {
"enum": [
"1",
"1-4",
"5-14",
"15-24",
"25-34",
"35-44",
"45-54",
"55-64",
"65-74",
"75-84",
"85+",
"NS"
],
"type": "string"
},
"description": "Restrict to deaths in any of the listed age groups — e.g. [\"25-34\",\"35-44\"] covers both; a repeated group counts once. \"1\" is the under-1-year group. \"NS\" is the group CDC puts a death in when the age was not recorded; it is not covered by any of the ten-year groups, so a filter listing all eleven of those still leaves those deaths out and returns fewer deaths than the same query unfiltered. CDC refuses \"NS\" beside only some of the other groups: list it on its own to count those deaths, or list all twelve values — the same as omitting age_groups — to include them. Omit for all ages, which includes them."
},
"year_range": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "integer",
"maximum": 2026,
"minimum": 1999,
"description": "Last year (1999–2026 across all databases; the selected one holds a narrower span)."
},
"from": {
"type": "integer",
"maximum": 2026,
"minimum": 1999,
"description": "First year (1999–2026 across all databases; the selected one holds a narrower span)."
}
},
"description": "Inclusive year range; from must not be later than to. These bounds span every database (1999–2026); the years the selected one actually holds are narrower, and a range outside them is rejected with that database's span named. Omit for all years the database holds."
},
"cause_icd10": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"const": "999--999"
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 underlying-cause code or range. WONDER takes a node of its ICD-10 tree — a chapter such as \"A00-B99\" (infectious) or \"V01-Y89\" (external causes), a block such as \"X40-X49\" (accidental poisoning) or \"C00-C97\" (malignant neoplasms), or a single code such as \"I21\" — and rejects any other span, e.g. \"X40-X44\", naming it in the error. List the codes (or blocks) to cover a span that is not a tree node."
},
{
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"const": "999--999"
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 underlying-cause code or range. WONDER takes a node of its ICD-10 tree — a chapter such as \"A00-B99\" (infectious) or \"V01-Y89\" (external causes), a block such as \"X40-X49\" (accidental poisoning) or \"C00-C97\" (malignant neoplasms), or a single code such as \"I21\" — and rejects any other span, e.g. \"X40-X44\", naming it in the error. List the codes (or blocks) to cover a span that is not a tree node."
}
],
"description": "One list entry: an ICD-10 code or range, or the withheld-cause marker."
},
"maxItems": 50,
"description": "A list of up to 50 entries, each in the single-value form, matched as a union: a death counts once when it matches any of them, so a code set such as X40–X44 plus X60–X64 is one series with one set of rates. Repeated entries are ignored. An empty list reads as omitted."
}
],
"description": "Filter to ICD-10 underlying causes of death — the single condition CDC certified as having started the chain of events leading to death. Takes one code or range, or a list of them for a cause defined as a code set, e.g. drug overdose as [\"X40\",\"X41\",\"X42\",\"X43\",\"X44\",\"X60\",\"X61\",\"X62\",\"X63\",\"X64\",\"X85\",\"Y10\",\"Y11\",\"Y12\",\"Y13\",\"Y14\"]. Omit for all causes. Accepted by every database. \"999--999\" is not an ICD-10 code but CDC's own marker for deaths whose cause it is still withholding under the provisional database's six-month reporting lag; it counts that backlog, and only the \"provisional\" database offers it."
}
},
"additionalProperties": false
}