clinical-trials-database
Query ClinicalTrials.gov via APIv2
Install / Use
npx skills add google-deepmind/science-skills --skill clinical_trials_databaseInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of clinical-trials-database
clinical-trials-database scores 88/100 on our quality scale, 367th of 606 Data & Analytics skills we index.
Its SKILL.md is 12 KB long, well organised into 20 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
With 3,137 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so clinical-trials-database is actively maintained.
- Our last check on 2026-11-01 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-02. Automated pattern scan on 2026-10-02. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
clinical-trials-database compared with similar skills
All 4 of these similar skills score higher than clinical-trials-database; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| clinical-trials-database (this skill)by google-deepmind | 88 | 3.1k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 9d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
| crawl4aiby unclecode | 100 | 87.4k | 3d ago | MCP Server |
Frequently asked questions
- How do I install clinical-trials-database?
- Run
npx skills add google-deepmind/science-skills --skill clinical-trials-database. The install tabs above show the steps for each supported agent. - Which AI agents does clinical-trials-database work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is clinical-trials-database safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is clinical-trials-database still maintained?
- The repository was last updated about 2 months ago, so clinical-trials-database is actively maintained.
Skill content
View source on GitHubname: clinical-trials-database description: > Query ClinicalTrials.gov via APIv2. Use when you want to search for trials by condition, drug, location, status, or phase; retrieve trial details by NCT ID; check eligibility/inclusion criteria; count trials across conditions or time periods; identify a sponsor's trial portfolio; find recruiting trials for patient matching.
Clinical Trials Database
Prerequisites
uv: Read theuvskill and follow its Setup instructions to ensureuvis 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-totalfirst — check result volume before fetching all records. - Paginate large result sets — use
--limitwith--page-tokento 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
references/studies_schema.mdto identify exact field paths for--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
--fieldsparameter to request specific data and keep responses small.
Top-Level Fields
totalCount— Total studies matching query (integer)studies[]— Array of study objectsnextPageToken— cursor string for pagination
Common Study Fields (and shorthand alias)
- Identification
protocolSection.identificationModule.nctId(NCTId) — Unique trial IDprotocolSection.identificationModule.briefTitle(BriefTitle) — Short title
- Status
protocolSection.statusModule.overallStatus(OverallStatus) — Recruitment status
- Description
protocolSection.descriptionModule.briefSummary(BriefSummary) — Short description
- Arms & Interventions
protocolSection.armsInterventionsModule.interventions(ArmsInterventionsModule)
- Eligibility
protocolSection.eligibilityModule.eligibilityCriteria(EligibilityCriteria) — Inclusion/ExclusionprotocolSection.eligibilityModule.stdAges(StdAge) — CHILD, ADULT, etc.
Consult references/studies_schema.md for full paths (Locations, Outcomes,
Results) and common --fields recipes.
Commands
Search for studies
Use for: finding trials by disease, drug, phase, status, age group, or any combination of these filters.
uv run scripts/clinical_trials_api.py search \
--condition "<disease>" \
--intervention "<drug_or_treatment>" \
--status "<status>" \
--phase "<phase>" \
--age-group "<age_group>" \
--study-type "<study_type>" \
--sponsor "<sponsor_name>" \
--has-results \
--sort "<field>:<asc|desc>" \
--fields "<fields>" \
--limit <N> \
--count-total \
--page-token "<token>" \
--output /tmp/search_results.json
All flags are optional and combine via AND logic.
Flag reference:
--condition— Disease or condition to search for (e.g."cystic fibrosis").--intervention— Drug, device, or treatment name (e.g."pembrolizumab").--status— Recruitment status filter. Values: RECRUITING, COMPLETED, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION, TERMINATED, SUSPENDED, WITHDRAWN.--phase— Trial phase filter. Values: PHASE1, PHASE2, PHASE3, PHASE4, EARLY_PHASE1, NA.--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 asFieldName:ascorFieldName: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"). Seereferences/studies_schema.mdfor 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 atotalCountfield 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 thenextPageTokenfield 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. Seereferences/clinical_trials_api.mdfor syntax.--output— (Required) File path where the JSON response is written.
Example — actively recruiting Phase 3 pediatric cystic fibrosis trials:
uv run scripts/clinical_trials_api.py search \
--condition "cystic fibrosis" \
--status RECRUITING \
--phase PHASE3 \
--age-group CHILD \
--fields "NCTId,BriefTitle,OverallStatus,Phase" \
--limit 10 \
--output /tmp/cf_trials.json
Example — recruiting atezolizumab trials for esophageal cancer:
uv run scripts/clinical_trials_api.py search \
--condition "esophageal cancer" \
--intervention "Atezolizumab" \
--status RECRUITING \
--fields "NCTId,BriefTitle,Phase" \
--limit 10 \
--output /tmp/atezolizumab_trials.json
Retrieve a study by NCT ID
Use for: fetching full details of a specific trial when you already have the NCT identifier.
uv run scripts/clinical_trials_api.py get-study \
<nct_id> [--fields "<fields>"] \
--output /tmp/study.json
Returns a useful default set of fields if --fields is omitted:
NCTId,BriefTitle,OverallStatus,Phase,BriefSummary,
ConditionsModule,ArmsInterventionsModule,EligibilityModule
Structure of the default response:
{
"protocolSection": {
"identificationModule": {
"nctId": "NCT00000000",
"briefTitle": "Study Title"
},
"statusModule": {
"overallStatus": "RECRUITING"
},
"descriptionModule": {
"briefSummary": "This study is about..."
},
"conditionsModule": {
"conditions": [ "Condition Name" ]
},
"armsInterventionsModule": {
"interventions": [ { "type": "DRUG", "name": "Drug Name" } ]
},
"eligibilityModule": {
"eligibilityCriteria": "Inclusion:\n- ...",
"stdAges": [ "ADULT" ]
}
}
}
Get eligibility / inclusion criteria
Use for: pulling inclusion/exclusion rules, age ranges, and sex requirements for patient-matching tasks.
uv run scripts/clinical_trials_api.py \
get-eligibility <nct_id> \
--output /tmp/eligibility.json
Shortcut that returns title and the full eligibility module (inclusion/exclusion criteria, age range, sex).
Example — inclusion criteria for NCT04886804:
uv run scripts/clinical_trials_api.py \
get-eligibility NCT04886804 \
--output /tmp/eligibility_NCT04886804.json
Count matching studies
Use for: exploring the trial landscape — checking how many trials exist for a condition, phase, or status before fetching full records.
uv run scripts/clinical_trials_api.py count \
--condition "<disease>" \
[--status "<status>"] [--phase "<phase>"] ... \
--output /tmp/count.json
Returns only the total count of clinical trials matching the search criteria
without fetching study records. Accepts the same filter flags as search.
Search by location / geography
Use for: narrowing trials to a specific country, state, or city.
Use --advanced with AREA[LocationCountry] or AREA[LocationCity] to
restrict results by geography:
uv run scripts/clinical_trials_api.py search \
--condition "cystic fibrosis" \
--status RECRUITING \
--advanced "AREA[LocationCity]New York" \
--fields "NCTId,BriefTitle" \
--limit 20 \
--output /tmp/nyc_cf_trials.json
Search by sponsor / organization
Use for: identifying a sponsor's or institution's trial portfolio.
Use --sponsor to find trials run by a specific institution or company:
uv run scripts/clinical_trials_api.py search \
--sponsor "National Cancer Institute" \
--fields "NCTId,BriefTitle,LeadSponsorName" \
--limit 20 \
--output /tmp/nci_trials.json
Combined multi-criteria search
Use for: complex queries that layer multiple filters (condition and drug and phase and geography and sponsor, etc.).
All flags combine via AND, so you can layer conditions, interventions, status, phase, geography, and sponsor in a single query:
uv run scripts/clinical_trials_api.py search \
--condition "pancreatic cancer" \
--intervention "immunotherapy" \
--status RECRUITING \
--phase PHASE3 \
--advanced "AREA[LocationCountry]United States" \
--fields "NCTId,BriefTitle,Phase,LeadSponsorName" \
--limit 20 \
--output /tmp/panc_trials.json
Raw API query (escape hatch)
Use for: uncommon endpoints or parameter combinations not covered by the dedicated flags.
uv run scripts/clinical_trials_api.py raw-query \
--endpoint <path> \
--params '<json_dict>' \
--output /tmp/raw_result.json
Pagination
When results exceed --limit, the response includes a nextPageToken. Pass it
with --page-token to fetch the next page:
uv run scripts/clinical_trials_api.py search \
--condition "breast cancer" \
--status RECRUITING \
--limit 50 --count-total \
--output /tmp/breast_cancer_p1.json
uv run scripts/clinical_trials_api.py search \
--condition "breast cancer" \
--status RECRUITING \
--limit 50 --page-token "CAo=" \
--output /tmp/breast_cancer_p2.json
Advanced Querying
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 StatesAREA[Phase]PHASE3
- Boolean operators: Combine with
AND,OR,NOT. - **`RANGE[min,
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.4kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
