clinicaltrials-database
Query ClinicalTrials.gov via API v2. Search trials by condition, drug, location, status, or phase. Retrieve trial details by NCT ID, export data, for clinical research and patient matching.
Install / Use
npx skills add foryourhealth111-pixel/Vibe-Skills --skill clinicaltrials-databaseInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of clinicaltrials-database
clinicaltrials-database scores 95/100 on our quality scale, 59th of 606 Data & Analytics skills we index (top 10%).
Its SKILL.md is 15 KB long, well organised into 41 sections with 19 code examples: a thorough specification that gives an agent plenty to work with.
With 3,433 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so clinicaltrials-database is actively maintained.
- Our last check on 2026-10-24 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.
clinicaltrials-database compared with similar skills
All 4 of these similar skills score higher than clinicaltrials-database; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| clinicaltrials-database (this skill)by foryourhealth111-pixel | 95 | 3.4k | 3mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d 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 clinicaltrials-database?
- Run
npx skills add foryourhealth111-pixel/Vibe-Skills --skill clinicaltrials-database. The install tabs above show the steps for each supported agent. - Which AI agents does clinicaltrials-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 clinicaltrials-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 clinicaltrials-database still maintained?
- The repository was last updated about 3 months ago, so clinicaltrials-database is actively maintained.
Skill content
View source on GitHubname: clinicaltrials-database description: Query ClinicalTrials.gov via API v2. Search trials by condition, drug, location, status, or phase. Retrieve trial details by NCT ID, export data, for clinical research and patient matching. license: Unknown metadata: skill-author: K-Dense Inc.
ClinicalTrials.gov Database
Overview
ClinicalTrials.gov is a comprehensive registry of clinical studies conducted worldwide, maintained by the U.S. National Library of Medicine. Access API v2 to search for trials, retrieve detailed study information, filter by various criteria, and export data for analysis. The API is public (no authentication required) with rate limits of ~50 requests per minute, supporting JSON and CSV formats.
When to Use This Skill
This skill should be used when working with clinical trial data in scenarios such as:
- Patient matching - Finding recruiting trials for specific conditions or patient populations
- Research analysis - Analyzing clinical trial trends, outcomes, or study designs
- Drug/intervention research - Identifying trials testing specific drugs or interventions
- Geographic searches - Locating trials in specific locations or regions
- Sponsor/organization tracking - Finding trials conducted by specific institutions
- Data export - Extracting clinical trial data for further analysis or reporting
- Trial monitoring - Tracking status updates or results for specific trials
- Eligibility screening - Reviewing inclusion/exclusion criteria for trials
Quick Start
Basic Search Query
Search for clinical trials using the helper script:
cd scientific-databases/clinicaltrials-database/scripts
python3 query_clinicaltrials.py
Or use Python directly with the requests library:
import requests
url = "https://clinicaltrials.gov/api/v2/studies"
params = {
"query.cond": "breast cancer",
"filter.overallStatus": "RECRUITING",
"pageSize": 10
}
response = requests.get(url, params=params)
data = response.json()
print(f"Found {data['totalCount']} trials")
Retrieve Specific Trial
Get detailed information about a trial using its NCT ID:
import requests
nct_id = "NCT04852770"
url = f"https://clinicaltrials.gov/api/v2/studies/{nct_id}"
response = requests.get(url)
study = response.json()
# Access specific modules
title = study['protocolSection']['identificationModule']['briefTitle']
status = study['protocolSection']['statusModule']['overallStatus']
Core Capabilities
1. Search by Condition/Disease
Find trials studying specific medical conditions or diseases using the query.cond parameter.
Example: Find recruiting diabetes trials
from scripts.query_clinicaltrials import search_studies
results = search_studies(
condition="type 2 diabetes",
status="RECRUITING",
page_size=20,
sort="LastUpdatePostDate:desc"
)
print(f"Found {results['totalCount']} recruiting diabetes trials")
for study in results['studies']:
protocol = study['protocolSection']
nct_id = protocol['identificationModule']['nctId']
title = protocol['identificationModule']['briefTitle']
print(f"{nct_id}: {title}")
Common use cases:
- Finding trials for rare diseases
- Identifying trials for comorbid conditions
- Tracking trial availability for specific diagnoses
2. Search by Intervention/Drug
Search for trials testing specific interventions, drugs, devices, or procedures using the query.intr parameter.
Example: Find Phase 3 trials testing Pembrolizumab
from scripts.query_clinicaltrials import search_studies
results = search_studies(
intervention="Pembrolizumab",
status=["RECRUITING", "ACTIVE_NOT_RECRUITING"],
page_size=50
)
# Filter by phase in results
phase3_trials = [
study for study in results['studies']
if 'PHASE3' in study['protocolSection'].get('designModule', {}).get('phases', [])
]
Common use cases:
- Drug development tracking
- Competitive intelligence for pharmaceutical companies
- Treatment option research for clinicians
3. Geographic Search
Find trials in specific locations using the query.locn parameter.
Example: Find cancer trials in New York
from scripts.query_clinicaltrials import search_studies
results = search_studies(
condition="cancer",
location="New York",
status="RECRUITING",
page_size=100
)
# Extract location details
for study in results['studies']:
locations_module = study['protocolSection'].get('contactsLocationsModule', {})
locations = locations_module.get('locations', [])
for loc in locations:
if 'New York' in loc.get('city', ''):
print(f"{loc['facility']}: {loc['city']}, {loc.get('state', '')}")
Common use cases:
- Patient referrals to local trials
- Geographic trial distribution analysis
- Site selection for new trials
4. Search by Sponsor/Organization
Find trials conducted by specific organizations using the query.spons parameter.
Example: Find trials sponsored by NCI
from scripts.query_clinicaltrials import search_studies
results = search_studies(
sponsor="National Cancer Institute",
page_size=100
)
# Extract sponsor information
for study in results['studies']:
sponsor_module = study['protocolSection']['sponsorCollaboratorsModule']
lead_sponsor = sponsor_module['leadSponsor']['name']
collaborators = sponsor_module.get('collaborators', [])
print(f"Lead: {lead_sponsor}")
if collaborators:
print(f" Collaborators: {', '.join([c['name'] for c in collaborators])}")
Common use cases:
- Tracking institutional research portfolios
- Analyzing funding organization priorities
- Identifying collaboration opportunities
5. Filter by Study Status
Filter trials by recruitment or completion status using the filter.overallStatus parameter.
Valid status values:
RECRUITING- Currently recruiting participantsNOT_YET_RECRUITING- Not yet open for recruitmentENROLLING_BY_INVITATION- Only enrolling by invitationACTIVE_NOT_RECRUITING- Active but no longer recruitingSUSPENDED- Temporarily haltedTERMINATED- Stopped prematurelyCOMPLETED- Study has concludedWITHDRAWN- Withdrawn prior to enrollment
Example: Find recently completed trials with results
from scripts.query_clinicaltrials import search_studies
results = search_studies(
condition="alzheimer disease",
status="COMPLETED",
sort="LastUpdatePostDate:desc",
page_size=50
)
# Filter for trials with results
trials_with_results = [
study for study in results['studies']
if study.get('hasResults', False)
]
print(f"Found {len(trials_with_results)} completed trials with results")
6. Retrieve Detailed Study Information
Get comprehensive information about specific trials including eligibility criteria, outcomes, contacts, and locations.
Example: Extract eligibility criteria
from scripts.query_clinicaltrials import get_study_details
study = get_study_details("NCT04852770")
eligibility = study['protocolSection']['eligibilityModule']
print(f"Eligible Ages: {eligibility.get('minimumAge')} - {eligibility.get('maximumAge')}")
print(f"Eligible Sex: {eligibility.get('sex')}")
print(f"\nInclusion Criteria:")
print(eligibility.get('eligibilityCriteria'))
Example: Extract contact information
from scripts.query_clinicaltrials import get_study_details
study = get_study_details("NCT04852770")
contacts_module = study['protocolSection']['contactsLocationsModule']
# Overall contacts
if 'centralContacts' in contacts_module:
for contact in contacts_module['centralContacts']:
print(f"Contact: {contact.get('name')}")
print(f"Phone: {contact.get('phone')}")
print(f"Email: {contact.get('email')}")
# Study locations
if 'locations' in contacts_module:
for location in contacts_module['locations']:
print(f"\nFacility: {location.get('facility')}")
print(f"City: {location.get('city')}, {location.get('state')}")
if location.get('status'):
print(f"Status: {location['status']}")
7. Pagination and Bulk Data Retrieval
Handle large result sets efficiently using pagination.
Example: Retrieve all matching trials
from scripts.query_clinicaltrials import search_with_all_results
# Get all trials (automatically handles pagination)
all_trials = search_with_all_results(
condition="rare disease",
status="RECRUITING"
)
print(f"Retrieved {len(all_trials)} total trials")
Example: Manual pagination with control
from scripts.query_clinicaltrials import search_studies
all_studies = []
page_token = None
max_pages = 10 # Limit to avoid excessive requests
for page in range(max_pages):
results = search_studies(
condition="cancer",
page_size=1000, # Max page size
page_token=page_token
)
all_studies.extend(results['studies'])
# Check for next page
page_token = results.get('pageToken')
if not page_token:
break
print(f"Retrieved {len(all_studies)} studies across {page + 1} pages")
8. Data Export to CSV
Export trial data to CSV format for analysis in spreadsheet software or data analysis tools.
Example: Export to CSV file
from scripts.query_clinicaltrials import search_studies
# Request CSV format
results = search_studies(
condition="heart disease",
status="RECRUITING",
format="csv",
page_size=1000
)
# Save to file
with open("heart_disease_trials.csv", "w") as f:
f.write(results)
print("Data exported to heart_disease_trials.csv")
Note: CSV format returns a string instead of JSON dictionary.
9. Extract and Summarize Study Information
Extract key information for quick overview or reporting.
Example: Create trial summary
from scripts.query_clinicaltrials import get_study_details, extract_study_summary
# Get details and extract summary
study = get_study_details("NCT04852770")
summary = extract_study_summary(study)
print(f"NCT ID: {summary['nct_id']}")
print(f"Title: {summary['title']}")
print(f"Status: {summary['status']}")
print(f"Phase: {', '.join(summary['phase'])}")
print(f"Enrollment: {summary['enrollment']}")
print(f"Last Update: {summary['last_update']}")
print(f"\nBrief Summary:\n{summary['brief_summary']}")
10. Combined Query Strategies
Combine multiple filters for targeted searches.
Example: Multi-criteria search
from scripts.query_clinicaltrials import search_studies
# Find Phase 2/3 immunotherapy trials for lung cancer in California
results = search_studies(
condition="lung cancer",
intervention="immunotherapy",
location="California",
status=["RECRUITING", "NOT_YET_RECRUITING"],
page_size=100
)
# Further filter by phase
phase2_3_trials = [
study for study in results['studies']
if any(phase in ['PHASE2', 'PHASE3']
for phase in study['protocolSection'].get('designModule', {}).get('phases', []))
]
print(f"Found {len(phase2_3_trials)} Phase 2/3 immunotherapy trials")
Resources
scripts/query_clinicaltrials.py
Comprehensive Python script providing helper functions for common query patterns:
search_studies()- Search for trials with various filtersget_study_details()- Retrieve full information for a specific trialsearch_with_all_results()- Automatically paginate through all resultsextract_study_summary()- Extract key information for quick overview
Run the script directly for example usage:
python3 scripts/query_clinicaltrials.py
references/api_reference.md
Detailed API documentation including:
- Complete endpoint specifications
- All query parameters and valid values
- Response data structure and modules
- Common use cases with code examples
- Error handling and best practices
- Data standards
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.