clinicaltrials_facet_counts
Retrieve exact per-value study counts across the entire ClinicalTrials.gov registry for up to 11 standard fields (status, phase, sponsor class, design) to analyze trial distributions.
Instructions
Aggregate EXACT per-value study counts over the WHOLE ClinicalTrials.gov registry for 1..11 whitelisted ENUM fields (keyless; clinicaltrials.gov/api/v2/stats/field/values). Input fields (deduped): OverallStatus, StudyType, Phase, LeadSponsorClass (NIH/FED/OTHER_GOV/INDUSTRY/OTHER/NETWORK/INDIV/UNKNOWN/AMBIG — richer than the 4-value funderType in the search tool), Sex, DesignAllocation, DesignPrimaryPurpose, DesignInterventionModel, DesignMasking, DesignObservationalModel, DesignTimePerspective. Returns { facets:[{ field, fieldPath, valueType, uniqueValuesCount, missingStudiesCount, returned, truncated, overlapping, values:[{value, studiesCount}] }] } + honest _meta. HONESTY: each studiesCount/uniqueValuesCount is EXACT (typeof NUMBER — non-number → schema_drift); non-ENUM shape for a whitelisted field → schema_drift. _meta.totalAvailable/returned count DISTINCT FIELD VALUES, NOT studies — see facets[].values[].studiesCount / clinicaltrials_search_studies for study counts. Counts cover the ENTIRE registry and are NOT filterable — /stats/field/values rejects query./filter./pageSize (HTTP 400). returned<uniqueValuesCount → truncated (hard cap 250). Phase is ARRAY-valued (overlapping:true, MUST NOT sum counts); scalar fields partition the registry minus missingStudiesCount. High missingStudiesCount → buckets cover a MINORITY of the registry. MANDATORY CAVEAT: facet counts are distributions over trial REGISTRATIONS, NOT federal awards; LeadSponsorClass is the funding-SOURCE class, not a UEI-keyed award join. Unlisted field → invalid_input pre-fetch; 404/400/5xx → THROWS.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | 1..11 ClinicalTrials.gov ENUM facet fields (deduped in-handler): OverallStatus, StudyType, Phase, LeadSponsorClass (★ the funding-SOURCE-class distribution — NIH/FED/OTHER_GOV/INDUSTRY/…, distinct from the search tool's 4-value funderType filter), Sex, DesignAllocation, DesignPrimaryPurpose, DesignInterventionModel, DesignMasking, DesignObservationalModel, DesignTimePerspective. Each returns the EXACT whole-registry per-value study-count distribution. An unlisted field ⇒ invalid_input pre-fetch (0 fetch). Phase is ARRAY-valued (counts OVERLAP — see _meta). |