Clinicaltrials api v2

ClinicalTrials.gov v2 API Guide

Overview

ClinicalTrials.gov is the world's largest clinical trial registry, maintained by the U.S. National Library of Medicine (NLM) at NIH. It contains over 576,000 study records from 220+ countries covering interventional trials, observational studies, and expanded access programs. The v2 API provides structured JSON access with field-level filtering, cursor-based pagination, and statistics endpoints.

Key v2 improvements over the legacy API: JSON-native responses, sparse field selection via the fields parameter, nextPageToken pagination, and dedicated statistics endpoints. Study data is organized into protocolSection (sponsor-submitted) and derivedSection (NLM-computed).

Authentication

No authentication required. All endpoints are publicly accessible without API keys or registration. Users should comply with NCBI usage policies and maintain reasonable request rates.

Core Endpoints

Search Studies

• URL: GET https://clinicaltrials.gov/api/v2/studies
• Parameters:

Parameter	Type	Required	Description
query.term	string	No	Free-text search across all fields
query.cond	string	No	Condition or disease filter
query.intr	string	No	Intervention or treatment filter
query.spons	string	No	Sponsor or collaborator filter
filter.overallStatus	string	No	RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING, etc.
filter.phase	string	No	EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA
filter.geo	string	No	Geographic filter (distance(lat,lng,dist))
fields	string	No	Comma-separated fields for sparse response
sort	string	No	Sort field and direction (e.g., LastUpdatePostDate:desc)
pageSize	int	No	Results per page (default 10, max 1000)
pageToken	string	No	Cursor token for next page
format	string	No	json (default) or csv

• Example:

curl "https://clinicaltrials.gov/api/v2/studies?query.cond=diabetes&query.intr=metformin&pageSize=1&fields=NCTId,BriefTitle,OverallStatus"

• Response:

{
  "studies": [{
    "protocolSection": {
      "identificationModule": {
        "nctId": "NCT06649773",
        "briefTitle": "The Experiment of Noiiglutide Injection in Type 2 Diabetes Patients"
      },
      "statusModule": { "overallStatus": "ACTIVE_NOT_RECRUITING" }
    }
  }],
  "nextPageToken": "ZVNj7o2Elu8o3lpo..."
}

Full responses include protocolSection with: identificationModule (NCT ID, titles, organization), statusModule (status, dates), descriptionModule (summary), conditionsModule, designModule (type, phases, enrollment), armsInterventionsModule, eligibilityModule (criteria, sex, age), outcomesModule, and contactsLocationsModule.

Get Single Study

• URL: GET https://clinicaltrials.gov/api/v2/studies/{nctId}

curl "https://clinicaltrials.gov/api/v2/studies/NCT04280705?fields=NCTId,BriefTitle,OverallStatus,Phase,LeadSponsorName,EnrollmentCount,Condition,InterventionName"

{
  "protocolSection": {
    "identificationModule": {
      "nctId": "NCT04280705",
      "briefTitle": "Adaptive COVID-19 Treatment Trial (ACTT)"
    },
    "statusModule": {
      "overallStatus": "COMPLETED",
      "startDateStruct": { "date": "2020-02-21" },
      "completionDateStruct": { "date": "2020-05-21" }
    },
    "sponsorCollaboratorsModule": {
      "leadSponsor": { "name": "National Institute of Allergy and Infectious Diseases (NIAID)" }
    },
    "conditionsModule": { "conditions": ["COVID-19"] },
    "designModule": { "phases": ["PHASE3"], "enrollmentInfo": { "count": 1062 } },
    "armsInterventionsModule": {
      "interventions": [{ "name": "Placebo" }, { "name": "Remdesivir" }]
    }
  }
}

Database Statistics

• URL: GET https://clinicaltrials.gov/api/v2/stats/size

curl "https://clinicaltrials.gov/api/v2/stats/size"

{
  "totalStudies": 576554,
  "averageSizeBytes": 17186,
  "largestStudies": [
    { "id": "NCT02723955", "sizeBytes": 3596689 },
    { "id": "NCT03688620", "sizeBytes": 2865033 }
  ]
}

Field Value Statistics

• URL: GET https://clinicaltrials.gov/api/v2/stats/fieldValues/{fieldName}

curl "https://clinicaltrials.gov/api/v2/stats/fieldValues/Phase"

{
  "type": "ENUM",
  "piece": "Phase",
  "field": "protocolSection.designModule.phases",
  "missingStudiesCount": 136632,
  "topValues": [
    { "value": "NA", "studiesCount": 222829 },
    { "value": "PHASE2", "studiesCount": 87478 },
    { "value": "PHASE1", "studiesCount": 63716 },
    { "value": "PHASE3", "studiesCount": 48700 },
    { "value": "PHASE4", "studiesCount": 34911 },
    { "value": "EARLY_PHASE1", "studiesCount": 6179 }
  ]
}

Rate Limits

No formal rate limits are published for the v2 API. Follow NCBI usage guidelines: stay under 3 requests/second without an API key, up to 10/second with one. For bulk data access, use the AACT relational database (https://aact.ctti-clinicaltrials.org/) or downloadable flat files rather than paginating through the full API.

Academic Use Cases

• Systematic reviews: Use query.cond + query.intr + filter.overallStatus=COMPLETED to build PRISMA-compliant trial inventories. Paginate with nextPageToken to collect all records, then extract outcomes and enrollment for quantitative synthesis.
• Landscape mapping: Combine search with stats/fieldValues to map phase distributions, sponsor concentration, and geographic spread for a therapeutic area -- useful for identifying evidence gaps in grant proposals.
• Recruitment tracking: Filter by RECRUITING status and filter.geo to find active enrollment opportunities. Automate periodic queries for new trials in your domain.

Code Examples

Paginated Collection for Systematic Review

import requests, time

def collect_trials(condition, intervention, status="COMPLETED"):
    base = "https://clinicaltrials.gov/api/v2/studies"
    studies, token = [], None
    while True:
        params = {
            "query.cond": condition, "query.intr": intervention,
            "filter.overallStatus": status, "pageSize": 100,
            "fields": "NCTId,BriefTitle,Phase,EnrollmentCount,CompletionDate",
        }
        if token:
            params["pageToken"] = token
        data = requests.get(base, params=params).json()
        studies.extend(data.get("studies", []))
        token = data.get("nextPageToken")
        if not token:
            break
        time.sleep(0.34)
    return studies

trials = collect_trials("type 2 diabetes", "metformin")
print(f"Collected {len(trials)} completed metformin T2D trials")

Sponsor and Phase Analysis

import requests
from collections import Counter

params = {"query.cond": "Alzheimer's Disease", "pageSize": 100,
          "fields": "NCTId,Phase,LeadSponsorName"}
data = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params).json()

phases, sponsors = Counter(), Counter()
for s in data["studies"]:
    p = s["protocolSection"]
    for ph in p.get("designModule", {}).get("phases", []):
        phases[ph] += 1
    sponsors[p.get("sponsorCollaboratorsModule", {})
              .get("leadSponsor", {}).get("name", "Unknown")] += 1

for ph, n in phases.most_common():
    print(f"{ph}: {n}")

References

• v2 API reference: https://clinicaltrials.gov/data-api/api
• About the API: https://clinicaltrials.gov/data-api/about-api
• AACT database (bulk access): https://aact.ctti-clinicaltrials.org/
• WHO ICTRP: https://trialsearch.who.int/
• NCBI usage policies: https://www.ncbi.nlm.nih.gov/home/about/policies/