ClinicalTrials.gov
The world's largest trial registry: roughly 560 000 studies, sponsor-submitted, going back to
2000. It answers the question that no bench assay can — has anyone already tried this in
people, and what happened to them when they did. For a target or an indication it is the
cheapest competitive and feasibility intelligence available.
Base URL: https://clinicaltrials.gov/api/v2 — REST, no key.
Docs: data-api ·
search areas
Checked against: the live v2 API, August 2026. The classic API was retired in June 2024.
Read references/api-reference.md before writing a query by hand,
references/study-structure.md before reaching for a field, and
references/reading-a-registry.md before drawing a conclusion
from anything you find — that one is judgement, not syntax.
The three scripts
| Script | Answers |
|---|
ct_search.py | What is registered against this condition or drug, and how much of it? |
ct_study.py | What exactly did this one study set out to do? |
ct_landscape.py | Who else is in this indication, and what stops trials here? |
COMPLETED does not mean it worked
This is the single thing to get right. overallStatus: COMPLETED means the study finished
running. It says nothing about whether the intervention succeeded — a trial that comprehensively
missed its primary endpoint completes normally.
Three separate facts, routinely conflated:
| Means |
|---|
overallStatus: COMPLETED | the study finished |
hasResults: true | results were posted to the registry |
| whether the endpoint was met | not recorded in the registry at all |
hasResults is a top-level sibling of protocolSection, not part of the status module, and it is
the easiest useful field to miss. ct_study.py show prints a warning when a study completed
without posting results.
Searching
python skills/clinicaltrials/scripts/ct_search.py search \
--condition "non-small cell lung cancer" --phase PHASE3 --limit 3
# 1019 studies match
nct_id status phase enrollment sponsor start has_results
NCT06357533 RECRUITING PHASE3 675 AstraZeneca 2024-04-11 false
NCT05278052 RECRUITING PHASE3 190 Tata Memorial Hospital 2020-04-20 false
NCT00268684 UNKNOWN PHASE3 381 Tel-Aviv Sourasky 2005-05 false
UNKNOWN is not an error: it is what the registry assigns when the sponsor has stopped verifying
the record. On a 2005 study, read it as "probably abandoned".
count --by phase and count --by status give the shape of a field without walking it. Note that
phase counts overlap — a phase 2/3 study carries ["PHASE2","PHASE3"] and is returned by a
filter for either — so they do not sum to the total.
One study in detail
python skills/clinicaltrials/scripts/ct_study.py show NCT02142738
python skills/clinicaltrials/scripts/ct_study.py outcomes NCT02142738
nct_id NCT02142738
status COMPLETED
phase PHASE3
allocation RANDOMIZED
enrollment 305 (ACTUAL)
sponsor Merck Sharp & Dohme LLC
start 2014-08-25
has_results True
outcomes separates the primary endpoint — what the study was powered for — from the
secondaries. A positive secondary in a study that missed its primary is hypothesis-generating,
not evidence, and the registry will not make that distinction for you.
eligibility splits the criteria blob back into inclusion and exclusion. There is no structured
form in the registry; it is one newline-delimited string with headings inside it.
Landscape and attrition
python skills/clinicaltrials/scripts/ct_landscape.py attrition \
--condition "pancreatic cancer" --phase PHASE3 --limit 120
phase studies completed recruiting terminated withdrawn stopped_pct
PHASE3 120 43 25 16 5 18.3
# 21 stated reasons for stopping
- Preliminary data showed no survival benefit in the GV1001 group compared to gemcitabine.
- recruitment prematurely stopped due to a lack of eligible patients.
whyStopped is the richest field in the registry and the reason attrition prints reasons
rather than counting them. Those two examples are completely different facts: the first is a real
negative result about the biology, often the only public record of it; the second says nothing
about the drug and everything about whether you can recruit for your own trial.
sponsors reports total enrolment and highest phase alongside the study count, because counting
registrations measures activity, not investment — twenty investigator-initiated phase 1s are not
two 800-patient phase 3s.
Four ways this registry misleads quietly
- Nobody verifies any of it. Sponsors submit and update at their own pace. A record is
evidence of stated intent, not of what happened.
- Drug names are free text with no identifier.
MK-3475, pembrolizumab, and Keytruda
do not group together. Resolve names with chembl first and search each synonym.
- Missing results usually mean nothing. FDAAA compliance is well below 100% and does not
reach phase 1, most non-US studies, or products never filed with the FDA.
ESTIMATED enrolment is a plan. Everything is estimated at registration; the gap between
it and the final ACTUAL is itself a feasibility finding.
When to stop using this API
The registry has no aggregation endpoint, so every breakdown here walks studies one page at a
time. For corpus-wide analysis, use the bulk download rather than the API. For European trials,
many of which never appear here, use the EU CTR; the WHO ICTRP federates the national registries.
Composing with the rest of the bundle
open-targets → here: is anyone already running trials against this target?chembl → here: resolve a compound's synonyms before searching free-text intervention names.openfda → alongside: the registry is what was attempted, openFDA is what was approved.depmap → here: a genetic dependency, checked against whether the clinic has tried it.pkpd-translation → after: a registered dose and schedule as a translation anchor.
Reporting results honestly
Give the query, the number of studies actually walked rather than the number matched, and the
date. Say "N studies are registered", never "N studies show". Quote whyStopped verbatim instead
of paraphrasing it into a cause. If asked whether a trial succeeded, say the registry does not
record that.