cms_query_dataset
Query CMS Open Payments datasets by ID, apply server-side filters, and retrieve rows, exact counts, and column schemas.
Instructions
Query a CMS Open Payments DKAN datastore distribution by datasetId + index (keyless; openpaymentsdata.cms.gov). Returns { datasetId, index, results (mode), fields:[{name,type,mysqlType,description}], rows:[…verbatim…] } + honest _meta. ★HONESTY: count is the EXACT grand total → totalAvailable=count + real offset pagination (NOT a page-length lower bound). conditions are server-side self-policing — BAD column → HTTP 400 → invalid_input; filtersDropped is ALWAYS empty (no silent-drop path). limit ≤ 500 is the HARD API cap (higher → invalid_input, no silent clamp). Every column is text, amounts arrive as STRINGS verbatim (null-never-0). ★results:false = COUNT/SCHEMA-discovery mode: no rows, pagination disabled (no livelock), EXACT count + column schema returned. Genuine {count:0} → honest empty; 400/404/HTML/5xx/timeout/missing schema/non-array → THROW. ★SSRF: datasetId (36-char UUID) + index are validated before URL interpolation. ★PII: Open Payments is PUBLIC transparency-BY-LAW data — bounded to targeted vetting (offset ≤ 2000 reach cap), NO enrichment, NO covered_recipient_npi→NPPES auto-join. NOT a conflict-of-interest / fitness / exclusion determination — cross-check SAM + OFAC + OIG-LEIE. The caveat + reach-cap disclosure ride EVERY response.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Distribution index (default 0 = the primary CSV). Also interpolates into the URL path (int 0..50). | |
| limit | No | Rows per page, 1..500, default 100. 500 is the HARD DKAN cap (the API 400s over it; this tool rejects >500 loudly). | |
| offset | No | 0-based row offset (default 0). ★POLICY reach cap ≤ 2000 (a deliberate targeted-lookup boundary — Open Payments names physicians + amounts); offset > 2000 ⇒ invalid_input. | |
| results | No | Default true (return rows). Set false for COUNT/SCHEMA-discovery mode: no rows, pagination disabled, but the EXACT count + every column's schema are returned. (`count` is NOT a toggle — count=true is always on the wire.) | |
| datasetId | Yes | REQUIRED — the DKAN datasetId, a 36-char LOWERCASE UUID. ★SSRF: it interpolates into the URL PATH, so this strict grammar (no uppercase, no %2F/../, no trailing newline) is the load-bearing path-injection guard. e.g. 'f0d1de67-6852-4093-a036-c9328c256a05' (2025 Research Payment Data). | |
| conditions | No | Server-side filters (≤10, AND-combined) that provably narrow the EXACT count. Each either applies or the call errors — filtersDropped is always empty. | |
| properties | No | Optional column projection (snake_case column names). Omit for all columns. |