uv: Read the uv skill and follow its Setup instructions to ensure
uv is installed and on PATH.
User Notification: If .licenses/clinical_trials_database_LICENSE.txt
does not already exist in the workspace root directory then (1) prominently
notify the user to check the terms at https://clinicaltrials.gov/, then (2)
create the file recording the notification text and timestamp.
Overview
Access worldwide clinical trial data from ClinicalTrials.gov via the REST API
v2. The CLI script at scripts/clinical_trials_api.py wraps the API with
dedicated flags for common filters (phase, age group, status, intervention,
sponsor, etc.) so you rarely need to construct raw queries.
Core Rules
Use the Wrapper: ALWAYS execute the provided helper scripts to query the
database rather than accessing the database directly. The scripts
automatically enforce the required rate limit gracefully.
Always use --fields — trial JSON records can be very large; restrict
to the data points you need.
Use --count-total first — check result volume before fetching all
records.
Paginate large result sets — use --limit with --page-token to
iterate.
Trust Search Filters: Do not manually re-filter results unless
explicitly asked to verify detailed eligibility.
Notification: If this skill is used, ensure this is mentioned in the
output.
Context Efficiency Warning
Trial JSON records can be very large. Always use the --fields parameter to
restrict the response to only the data points you need. After writing to file,
read only the fields you need rather than the entire file.
[!TIP] Use to identify exact field paths for
.
references/studies_schema.md
--fields
Response Layout Summary
API responses contain a list of studies (usually in a studies[] array). Each
study is split into protocolSection and optional resultsSection.
[!Tip] Use the shorthand aliases below with the --fields parameter to
request specific data and keep responses small.
Top-Level Fields
totalCount — Total studies matching query (integer)
studies[] — Array of study objects
nextPageToken — cursor string for pagination
Common Study Fields (and shorthand alias)
Identification
protocolSection.identificationModule.nctId (NCTId) — Unique trial ID
protocolSection.identificationModule.briefTitle (BriefTitle) — Short
title
Status
protocolSection.statusModule.overallStatus (OverallStatus) —
Recruitment status
Description
protocolSection.descriptionModule.briefSummary (BriefSummary) —
Short description
--age-group — Patient age group filter. Values: CHILD (0–17), ADULT
(18–64), OLDER_ADULT (65+).
--study-type — Type of study. Values: INTERVENTIONAL, OBSERVATIONAL,
EXPANDED_ACCESS.
--sponsor — Lead sponsor or institution name (e.g. "National Cancer Institute").
--has-results — Boolean flag (no value needed). When present, filters for
studies that have results available on ClinicalTrials.gov.
--sort — Sort order as FieldName:asc or FieldName:desc. Common fields:
LastUpdatePostDate, EnrollmentCount, StudyFirstPostDate, StartDate.
--fields — Comma-separated list of JSON field names to include in the
response. Use this to keep responses small (e.g.
"NCTId,BriefTitle,OverallStatus,Phase"). See
references/studies_schema.md for available field paths.
--limit — Maximum number of studies to return per request (1–1000, default
10).
--count-total — Boolean flag (no value needed). When present, the response
includes a totalCount field showing the total number of matching studies
across all pages.
--page-token — An opaque cursor string used to fetch the next page of
results. Obtain this value from the nextPageToken field in a previous
search response. Do not construct this string yourself; always copy it
verbatim from the API response. See the Pagination section below.
--advanced — Raw Essie filter expression for structured queries beyond the
dedicated flags (e.g. "AREA[LocationCountry]United States"). Combined with
other flags via AND. See references/clinical_trials_api.md for syntax.
--output — (Required) File path where the JSON response is written.
Example — actively recruiting Phase 3 pediatric cystic fibrosis trials:
Returns a useful default set of fields if --fields is omitted:
NCTId,BriefTitle,OverallStatus,Phase,BriefSummary,ConditionsModule,ArmsInterventionsModule,EligibilityModule
For complex filtering beyond the dedicated flags, use --advanced with an Essie
expression.
What is an Essie Expression? Essie is the search engine powering
ClinicalTrials.gov. An Essie expression is a structured query that targets
specific fields (e.g., country, phase) rather than doing general keyword
searches.
AREA[Field]Value: Targets a specific field.
AREA[LocationCountry]United States
AREA[Phase]PHASE3
Boolean operators: Combine with AND, OR, NOT.
RANGE[min, max]: For numeric/date fields (e.g. RANGE[500, MAX]).
See references/clinical_trials_api.md for syntax and available fields.
It is combined with other flags via AND:
uv run scripts/clinical_trials_api.py search \
--condition "diabetes" \
--advanced "AREA[LocationCountry]United States \
AND AREA[EnrollmentCount]RANGE[500, MAX]" \
--fields "NCTId,BriefTitle,EnrollmentCount" \
--output /tmp/diabetes_us_large.json
References
API parameters, enum values, and Essie syntax:references/clinical_trials_api.md
JSON field paths and --fields recipes:references/studies_schema.md
