searching-clinicaltrials

Searching ClinicalTrials.gov (v2 REST API)

Query ClinicalTrials.gov — the U.S. registry of clinical studies — for trials matching a condition, intervention, and recruitment status. This skill uses the modern v2 REST API (/api/v2/studies), which returns structured JSON and paginates with an opaque cursor (pageToken), not page numbers.

The v2 API is fully public: no API key, no registration, no license barrier. The legacy v1/classic API and the older query_term-style endpoints are deprecated — do not build on them.

When to use

• OpenMed extracted a diagnosis ("metastatic colorectal cancer") or a drug ("pembrolizumab") and you want open trials for it.
• You are building a patient-to-trial matching feature and need candidate studies before applying eligibility logic (parsing-trial-eligibility).
• You need a corpus of trial records (eligibility text, outcomes) to feed back into openmed.analyze_text for biomedical NER.

If you already have an NCT number, fetch the single study directly (/api/v2/studies/NCT01234567) instead of searching.

Quick start (real v2 API call)

Base URL: https://clinicaltrials.gov/api/v2. No auth. JSON by default.

import requests

BASE = "https://clinicaltrials.gov/api/v2"

def search_trials(condition: str, intervention: str | None = None,
                  status: str = "RECRUITING", page_size: int = 50) -> dict:
    """One page of studies for a condition (+ optional intervention)."""
    params = {
        "query.cond": condition,            # condition / disease search
        "filter.overallStatus": status,     # comma-separated enum values
        "pageSize": min(page_size, 1000),   # max 1000; default 10
        "countTotal": "true",               # include totalCount on first page
        "format": "json",
    }
    if intervention:
        params["query.intr"] = intervention  # drug / intervention search
    r = requests.get(f"{BASE}/studies", params=params, timeout=30)
    r.raise_for_status()
    return r.json()

data = search_trials("breast cancer", intervention="trastuzumab")
print(data["totalCount"])                    # total matches (first page only)
for study in data["studies"]:
    ps = study["protocolSection"]
    nct = ps["identificationModule"]["nctId"]
    title = ps["identificationModule"]["briefTitle"]
    print(nct, "-", title)