Clinicaltrials

ClinicalTrials.gov

The world's largest trial registry: roughly 560 000 studies, sponsor-submitted, going back to

1. 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](references/api-reference.md) before writing a query by hand, [references/study-structure.md](references/study-structure.md) before reaching for a field, and [references/reading-a-registry.md](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

1. Nobody verifies any of it. Sponsors submit and update at their own pace. A record is

evidence of stated intent, not of what happened.

1. 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.

1. 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.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: K-Dense-AI
• Source: K-Dense-AI/drug-discovery-agent-skills
• License: MIT
• Homepage: www.k-dense.ai

Install and usage instructions live in the source repository linked above.