Cdc Get Dataset Schema
cdc_get_dataset_schemaRead-only
Fetch the column schema for a CDC dataset — names, data types, descriptions, row count, last-updated timestamp, and, for a filter, the dataset it is a view of — with the period and area it covers, how often it is updated, its suggested citation, license, and attribution wherever the publisher recorded them. A chart or map has no schema of its own; the failure names the dataset it is built on. 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"datasetId": "<datasetId>"
},
"name": "cdc_get_dataset_schema"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | 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. | data.cdc.gov |
| datasetId | Yes | Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets. | |
| column_limit | No | 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 | No | 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 | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The column_limit that bounded this response. | |
| name | No | Dataset display name from the catalog (e.g., "Provisional COVID-19 Deaths by Sex and Age"). | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of columns returned in this response. | |
| notice | No | Guidance when the response is a subset of the schema — which columns it covers, how to reach the rest, or that column_offset ran past the end. | |
| columns | No | The requested window of dataset columns, with full types and descriptions. Bounded by column_limit/column_offset; the enrichment fields say how the window sits in the whole schema. | |
| license | No | Name of the license the dataset is published under — publisher-written text in no fixed format ("Public Domain U.S. Government", "Open Data Commons Attribution License"). Absent when the publisher named none. | |
| citation | No | How the publisher asks the dataset to be cited — publisher-written text in no fixed format, placeholders such as "[Last accessed date]" included. Absent when the publisher recorded none. | |
| parentId | No | Four-by-four ID of the dataset this asset is a view of — set on a filter, naming the dataset it was derived from. Absent on a dataset in its own right. | |
| rowCount | No | Total rows in the dataset; omitted when neither a live nor a cached figure is available. Read rowCountSource before sizing a pagination walk against it — the cached figure can understate an actively-updated dataset by a third or more. | |
| truncated | No | True when the returned columns are a subset of the schema. Absent means every column of the dataset is in this response. | |
| updatedAt | No | Last data update timestamp when provided. | |
| nextOffset | No | Value to pass as column_offset on the next call to continue after the last column returned. Present only when columns remain beyond this window. | |
| totalCount | No | Total columns in the dataset schema, before column_limit/column_offset. | |
| attribution | No | The office the publisher credits for the dataset — publisher-written text in no fixed format ("National Center for Health Statistics"). Absent when the publisher recorded none. | |
| description | No | Dataset description when provided, as plain text — markup stripped and entity references decoded. Capped at 4,000 characters by default and ending in "…" when cut, with descriptionTruncated and descriptionLength set; pass full_description: true for the whole text. Column descriptions are never shortened. | |
| rowCountSource | No | Provenance of rowCount. "live" is a count(*) run against the dataset for this call. "cached" is the figure Socrata stored when it last built its column cache, returned when the count request did not succeed; Socrata does not refresh it as rows land. Absent exactly when rowCount is absent. | |
| updateFrequency | No | How often the publisher updates the dataset — publisher-written text in no fixed format ("R/P1M", "Weekly", "irregular", "No longer updated (dataset archived)"). Absent when the publisher recorded none; updatedAt is when the data last changed, which alone does not tell a monthly series from a closed one. | |
| temporalCoverage | No | Period the data covers — publisher-written text in no fixed format, relayed as written ("2015-01-01/2026-05-31", "1999/2018", "2019/present", "N/A"). Absent when the publisher recorded none. | |
| descriptionLength | No | Character count of the whole description, present only when description was cut. Call again with full_description: true to read all of it. | |
| geographicCoverage | No | Area the data covers — publisher-written text in no fixed format ("United States", "50 states and District of Columbia"). Absent when the publisher recorded none. | |
| descriptionTruncated | No | True when description was cut at the 4,000-character cap. Absent means description is the whole text. |