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.
\nThis skill should be used when working with clinical trial data in scenarios such as:
\n| Scenario | \nUse Instead | \n
|---|---|
| Published trial results, RCT papers, or meta-analysis literature | \nalterlab-pubmed | \n
| FDA approvals, drug labels, adverse-event (FAERS) or recall data | \nalterlab-fda | \n
| Writing a CSR, SAE narrative, or other trial report document | \nalterlab-clinical-reports | \n
| Evidence-graded treatment recommendations / decision algorithms | \nalterlab-clinical-decision | \n
Run the helper script (from this skill's scripts/ directory):
python3 scripts/query_clinicaltrials.py\nOr use Python directly with the requests library. Note: the API omits\ntotalCount unless you pass countTotal=true, and the pagination token is\nreturned as nextPageToken.
import requests\n\nurl = \"https://clinicaltrials.gov/api/v2/studies\"\nparams = {\n \"query.cond\": \"breast cancer\",\n \"filter.overallStatus\": \"RECRUITING\",\n \"pageSize\": 10,\n \"countTotal\": \"true\", # required for data['totalCount'] to exist\n}\n\nresponse = requests.get(url, params=params)\ndata = response.json()\n\nprint(f\"Found {data['totalCount']} trials\")\nGet detailed information about a trial using its NCT ID:
\nimport requests\n\nnct_id = \"NCT04852770\"\nurl = f\"https://clinicaltrials.gov/api/v2/studies/{nct_id}\"\n\nresponse = requests.get(url)\nstudy = response.json()\n\n# Access specific modules\ntitle = study['protocolSection']['identificationModule']['briefTitle']\nstatus = study['protocolSection']['statusModule']['overallStatus']\nFind trials studying specific medical conditions or diseases using the query.cond parameter.
Example: Find recruiting diabetes trials
\nfrom scripts.query_clinicaltrials import search_studies\n\nresults = search_studies(\n condition=\"type 2 diabetes\",\n status=\"RECRUITING\",\n page_size=20,\n sort=\"LastUpdatePostDate:desc\"\n)\n\nprint(f\"Found {results['totalCount']} recruiting diabetes trials\")\nfor study in results['studies']:\n protocol = study['protocolSection']\n nct_id = protocol['identificationModule']['nctId']\n title = protocol['identificationModule']['briefTitle']\n print(f\"{nct_id}: {title}\")\nCommon use cases:
\nSearch for trials testing specific interventions, drugs, devices, or procedures using the query.intr parameter.
Example: Find Phase 3 trials testing Pembrolizumab
\nfrom scripts.query_clinicaltrials import search_studies\n\nresults = search_studies(\n intervention=\"Pembrolizumab\",\n status=[\"RECRUITING\", \"ACTIVE_NOT_RECRUITING\"],\n page_size=50\n)\n\n# Filter by phase in results\nphase3_trials = [\n study for study in results['studies']\n if 'PHASE3' in study['protocolSection'].get('designModule', {}).get('phases', [])\n]\n\n\nPhase filtering note: There is no
\nfilter.phasequery parameter — passing\none returns HTTP 400. To filter server-side, useaggFilters=phase:Nwhere N is\n0–4 (values within a facet are space-separated, e.g.aggFilters=phase:2 3for\nPhase 2 or 3), orfilter.advanced=AREA[Phase](PHASE2 OR PHASE3)with Essie\nsyntax. Post-filtering ondesignModule.phases(as above) is the simplest\napproach when you already need the full records.
Common use cases:
\nFind trials in specific locations using the query.locn parameter.
Example: Find cancer trials in New York
\nfrom scripts.query_clinicaltrials import search_studies\n\nresults = search_studies(\n condition=\"cancer\",\n location=\"New York\",\n status=\"RECRUITING\",\n page_size=100\n)\n\n# Extract location details\nfor study in results['studies']:\n locations_module = study['protocolSection'].get('contactsLocationsModule', {})\n locations = locations_module.get('locations', [])\n for loc in locations:\n if 'New York' in loc.get('city', ''):\n print(f\"{loc['facility']}: {loc['city']}, {loc.get('state', '')}\")\nCommon use cases:
\nFind trials conducted by specific organizations using the query.spons parameter.
Example: Find trials sponsored by NCI
\nfrom scripts.query_clinicaltrials import search_studies\n\nresults = search_studies(\n sponsor=\"National Cancer Institute\",\n page_size=100\n)\n\n# Extract sponsor information\nfor study in results['studies']:\n sponsor_module = study['protocolSection']['sponsorCollaboratorsModule']\n lead_sponsor = sponsor_module['leadSponsor']['name']\n collaborators = sponsor_module.get('collaborators', [])\n print(f\"Lead: {lead_sponsor}\")\n if collaborators:\n print(f\" Collaborators: {', '.join([c['name'] for c in collaborators])}\")\nCommon use cases:
\nFilter trials by recruitment or completion status using the filter.overallStatus parameter.
Valid status values:
\nRECRUITING - 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 enrollmentAVAILABLE, NO_LONGER_AVAILABLE,\nTEMPORARILY_NOT_AVAILABLE, APPROVED_FOR_MARKETING; WITHHELD and UNKNOWN\nalso occur (full list: GET /api/v2/studies/enums)Example: Find recently completed trials with results
\nfrom scripts.query_clinicaltrials import search_studies\n\nresults = search_studies(\n condition=\"alzheimer disease\",\n status=\"COMPLETED\",\n sort=\"LastUpdatePostDate:desc\",\n page_size=50\n)\n\n# Filter for trials with results\ntrials_with_results = [\n study for study in results['studies']\n if study.get('hasResults', False)\n]\n\nprint(f\"Found {len(trials_with_results)} completed trials with results\")\nGet comprehensive information about specific trials including eligibility criteria, outcomes, contacts, and locations.
\nExample: Extract eligibility criteria
\nfrom scripts.query_clinicaltrials import get_study_details\n\nstudy = get_study_details(\"NCT04852770\")\neligibility = study['protocolSection']['eligibilityModule']\n\nprint(f\"Eligible Ages: {eligibility.get('minimumAge')} - {eligibility.get('maximumAge')}\")\nprint(f\"Eligible Sex: {eligibility.get('sex')}\")\nprint(f\"\\nInclusion Criteria:\")\nprint(eligibility.get('eligibilityCriteria'))\nExample: Extract contact information
\nfrom scripts.query_clinicaltrials import get_study_details\n\nstudy = get_study_details(\"NCT04852770\")\ncontacts_module = study['protocolSection']['contactsLocationsModule']\n\n# Overall contacts\nif 'centralContacts' in contacts_module:\n for contact in contacts_module['centralContacts']:\n print(f\"Contact: {contact.get('name')}\")\n print(f\"Phone: {contact.get('phone')}\")\n print(f\"Email: {contact.get('email')}\")\n\n# Study locations\nif 'locations' in contacts_module:\n for location in contacts_module['locations']:\n print(f\"\\nFacility: {location.get('facility')}\")\n print(f\"City: {location.get('city')}, {location.get('state')}\")\n if location.get('status'):\n print(f\"Status: {location['status']}\")\nHandle large result sets efficiently using pagination.
\nExample: Retrieve all matching trials
\nfrom scripts.query_clinicaltrials import search_with_all_results\n\n# Get all trials (automatically handles pagination)\nall_trials = search_with_all_results(\n condition=\"rare disease\",\n status=\"RECRUITING\"\n)\n\nprint(f\"Retrieved {len(all_trials)} total trials\")\nExample: Manual pagination with control
\nfrom scripts.query_clinicaltrials import search_studies\n\nall_studies = []\npage_token = None\nmax_pages = 10 # Limit to avoid excessive requests\n\nfor page in range(max_pages):\n results = search_studies(\n condition=\"cancer\",\n page_size=1000, # Max page size\n page_token=page_token\n )\n\n all_studies.extend(results['studies'])\n\n # Check for next page. The API returns the cursor as 'nextPageToken';\n # you pass it back in as the 'pageToken' request parameter.\n page_token = results.get('nextPageToken')\n if not page_token:\n break\n\nprint(f\"Retrieved {len(all_studies)} studies across {page + 1} pages\")\nExport trial data to CSV format for analysis in spreadsheet software or data analysis tools.
\nExample: Export to CSV file
\nfrom scripts.query_clinicaltrials import search_studies\n\n# Request CSV format\nresults = search_studies(\n condition=\"heart disease\",\n status=\"RECRUITING\",\n format=\"csv\",\n page_size=1000\n)\n\n# Save to file\nwith open(\"heart_disease_trials.csv\", \"w\") as f:\n f.write(results)\n\nprint(\"Data exported to heart_disease_trials.csv\")\nNote: CSV format returns a string instead of JSON dictionary.
\nExtract key information for quick overview or reporting.
\nExample: Create trial summary
\nfrom scripts.query_clinicaltrials import get_study_details, extract_study_summary\n\n# Get details and extract summary\nstudy = get_study_details(\"NCT04852770\")\nsummary = extract_study_summary(study)\n\nprint(f\"NCT ID: {summary['nct_id']}\")\nprint(f\"Title: {summary['title']}\")\nprint(f\"Status: {summary['status']}\")\nprint(f\"Phase: {', '.join(summary['phase'])}\")\nprint(f\"Enrollment: {summary['enrollment']}\")\nprint(f\"Last Update: {summary['last_update']}\")\nprint(f\"\\nBrief Summary:\\n{summary['brief_summary']}\")\nCombine multiple filters for targeted searches.
\nExample: Multi-criteria search
\nfrom scripts.query_clinicaltrials import search_studies\n\n# Find Phase 2/3 immunotherapy trials for lung cancer in California\nresults = search_studies(\n condition=\"lung cancer\",\n intervention=\"immunotherapy\",\n location=\"California\",\n status=[\"RECRUITING\", \"NOT_YET_RECRUITING\"],\n page_size=100\n)\n\n# Further filter by phase\nphase2_3_trials = [\n study for study in results['studies']\n if any(phase in ['PHASE2', 'PHASE3']\n for phase in study['protocolSection'].get('designModule', {}).get('phases', []))\n]\n\nprint(f\"Found {len(phase2_3_trials)} Phase 2/3 immunotherapy trials\")\nscripts/query_clinicaltrials.py — helpers for the common query patterns:\nsearch_studies(), get_study_details(), search_with_all_results()\n(auto-pagination), extract_study_summary(). Run directly for example usage.references/api_reference.md — full endpoint/parameter specs, response\nmodules, error handling, and data standards (ISO 8601, CommonMark). Load when\nworking with unfamiliar API features or troubleshooting.The API has a rate limit of approximately 50 requests per minute. For bulk data retrieval:
\nimport time\nimport requests\n\ndef search_with_rate_limit(params):\n try:\n response = requests.get(\"https://clinicaltrials.gov/api/v2/studies\", params=params)\n response.raise_for_status()\n return response.json()\n except requests.exceptions.HTTPError as e:\n if e.response.status_code == 429:\n print(\"Rate limited. Waiting 60 seconds...\")\n time.sleep(60)\n return search_with_rate_limit(params) # Retry\n raise\nThe API response has a nested structure. Key paths to common information:
\nstudy['protocolSection']['identificationModule']['nctId']study['protocolSection']['identificationModule']['briefTitle']study['protocolSection']['statusModule']['overallStatus']study['protocolSection']['designModule']['phases']study['protocolSection']['eligibilityModule']study['protocolSection']['contactsLocationsModule']['locations']study['protocolSection']['armsInterventionsModule']['interventions']Use a timeout on every request and treat HTTP 400 as a query bug, not \"no trials\":\nthe API rejects unknown parameters (e.g. filter.phase) and malformed Essie\nexpressions with 400.
Not all trials have complete information. Always check for field existence:
\n# Safe navigation with .get()\nphases = study['protocolSection'].get('designModule', {}).get('phases', [])\nenrollment = study['protocolSection'].get('designModule', {}).get('enrollmentInfo', {}).get('count', 'N/A')\n\n# Check before accessing\nif 'resultsSection' in study:\n # Process results\n pass\nhttps://clinicaltrials.gov/api/v2GET /api/v2/version reports the current build, 2.0.5 as of 2026-09, plus the data timestamp)For complete technical details, see references/api_reference.md.