Guides
ClinicalTrials.gov API v2: query studies, fields and paging (with Python)
The ClinicalTrials.gov API v2 lives at https://clinicaltrials.gov/api/v2 and needs no API key. To search, send a GET to /studies with query.cond (condition), query.term (other terms) and filter.overallStatus, choose the fields you want with fields, and follow nextPageToken into pageToken until the response stops returning one. The classic API under /api/query/ was retired on June 25, 2024, and old code that calls it now gets HTTP 404.
Everything below was checked against the OpenAPI spec (API version 2.0.5) and the API Migration Guide, and every request was run against the live API on 2026-11-13. Result counts will have changed by the time you run them.
ClinicalTrials.gov API base URL and access
The base URL is https://clinicaltrials.gov/api/v2, and you call it with plain HTTPS GET requests and no key or sign-up. The OpenAPI spec defines no authentication scheme, and none of the requests in this guide sent a key. Responses are JSON by default; /studies also returns CSV with format=csv.
| Endpoint | What it returns |
|---|---|
GET /studies |
Studies matching your query and filters, one page at a time |
GET /studies/{nctId} |
One study by its NCT number |
GET /studies/metadata |
Every field name in the study data model |
GET /studies/search-areas |
The search areas behind each query.* parameter |
GET /studies/enums |
Allowed values for enum fields, with their classic API equivalents |
GET /stats/field/values |
Value counts for study fields, across all studies |
GET /version |
The API version and dataTimestamp, the time of the last data refresh |
The API page says data is refreshed “daily Monday through Friday, generally by 9 a.m. ET (14:00 UTC)” and tells you to check dataTimestamp on /version to confirm a refresh has finished. The same page notes that since a data ingest change on August 26, 2025, some formatted text fields and the location and geopoint data come from a different pipeline than before.
How to search studies by condition, term or status
You search by condition with query.cond, by free text with query.term, and narrow by recruitment status with filter.overallStatus. This request returns two recruiting asthma studies with only their ID and title:
curl "https://clinicaltrials.gov/api/v2/studies?query.cond=asthma&filter.overallStatus=RECRUITING&fields=NCTId,BriefTitle&pageSize=2"The response is {"studies": [...], "nextPageToken": "..."}. Each study is nested: the ID is at protocolSection.identificationModule.nctId.
The query.* parameters search different parts of a record. They use the site’s Essie expression syntax, so (head OR neck) AND pain works, and they affect ranking when you sort by relevance.
| Parameter | Searches |
|---|---|
query.cond |
Conditions or disease |
query.term |
Other terms (the classic API’s expr goes here) |
query.intr |
Intervention or treatment |
query.spons |
Sponsor or collaborator |
query.lead |
Lead sponsor name only |
query.titles |
Title or acronym |
query.outc |
Outcome measures |
query.locn |
Location terms |
query.id |
Study IDs |
filter.overallStatus takes a comma- or pipe-separated list. The allowed values are ACTIVE_NOT_RECRUITING, COMPLETED, ENROLLING_BY_INVITATION, NOT_YET_RECRUITING, RECRUITING, SUSPENDED, TERMINATED, WITHDRAWN, AVAILABLE, NO_LONGER_AVAILABLE, TEMPORARILY_NOT_AVAILABLE, APPROVED_FOR_MARKETING, WITHHELD and UNKNOWN. Other filters are filter.geo (for example distance(39.0035707,-77.1013313,50mi)), filter.ids for a list of NCT numbers, and filter.advanced for any Essie expression. Filters do not change ranking. One trap from the spec: if any query parameter contains only NCT IDs, the filters are ignored.
To combine an intervention, a phase, a date range and a sort order, let curl encode the brackets:
curl -G "https://clinicaltrials.gov/api/v2/studies" \ --data-urlencode "query.intr=semaglutide" \ --data-urlencode "filter.advanced=AREA[Phase]PHASE3" \ --data-urlencode "query.term=AREA[LastUpdatePostDate]RANGE[2025-01-01,MAX]" \ --data-urlencode "sort=LastUpdatePostDate:desc" \ --data-urlencode "fields=NCTId,Phase,LastUpdatePostDate" \ --data-urlencode "pageSize=3"Results are not sorted by default, which the spec says is for performance. sort takes up to two date or numeric fields, each with an optional :asc or :desc, or @relevance. Date fields sort descending and numeric fields ascending unless you say otherwise, and studies missing the sort field always come last.
How to choose fields: enrollment, phase and dates
You choose fields by passing a comma- or pipe-separated list of field names to fields; leave it out and you get every field of every study, which is large. Field names in the request are short (EnrollmentCount), but the response keeps the full nested structure, so you need the path. These paths were read from live responses:
fields name |
JSON path in the response |
|---|---|
NCTId |
protocolSection.identificationModule.nctId |
BriefTitle |
protocolSection.identificationModule.briefTitle |
OverallStatus |
protocolSection.statusModule.overallStatus |
Phase |
protocolSection.designModule.phases (a list, such as ["PHASE3"]) |
EnrollmentCount |
protocolSection.designModule.enrollmentInfo.count |
StartDate |
protocolSection.statusModule.startDateStruct.date |
PrimaryCompletionDate |
protocolSection.statusModule.primaryCompletionDateStruct.date |
LastUpdatePostDate |
protocolSection.statusModule.lastUpdatePostDateStruct.date |
LeadSponsorName |
protocolSection.sponsorCollaboratorsModule.leadSponsor.name |
A study without a value simply lacks the key: in a recruiting asthma search on 2026-11-13, the first two studies came back with no phases key at all. Phase values are NA, EARLY_PHASE1, PHASE1 to PHASE4. Dates are ISO 8601 and can be yyyy, yyyy-MM or yyyy-MM-dd, so do not assume a full date. You can also name a whole module, such as ConditionsModule or ProtocolSection, to get everything under it. GET /studies/metadata lists every field name.
CSV uses different names. With format=csv, fields=NCTId fails with 400 “Parameter ‘fields’ contains invalid CSV column name: ‘NCTId’”; ask for the CSV column names instead, such as NCT Number,Study Title,Phases,Enrollment, as listed on the CSV Download page.
How to page through results with pageToken
You page by copying nextPageToken from each response into the pageToken parameter of the next request, with every other parameter unchanged, and you stop when a response has no nextPageToken. The default page size is 10. pageSize can be set up to 1,000; the spec says larger values are coerced down to 1,000.
Three rules from the spec matter in code:
- Keep the parameters. Every later page must use the same parameters as the first, except
countTotal,pageSizeandpageToken. - Stop on the token, not on an empty list. A page may come back with an empty
studiesarray before the end. - Count once.
countTotalis ignored after the first page.
For CSV, the token comes in the x-next-page-token response header instead of the body.
How to count results without downloading them
You count matching studies with countTotal=true, which adds totalCount to the first page. Ask for one study and one field so the response stays small:
curl "https://clinicaltrials.gov/api/v2/studies?query.cond=asthma&filter.overallStatus=RECRUITING&countTotal=true&fields=NCTId&pageSize=1"On 2026-11-13 this returned "totalCount":375. With no query or filter at all, the same request counted 611,771 studies in the registry. For CSV, the count is in the x-total-count response header.
How to get one study by NCT ID
You fetch one study with GET /studies/{nctId}, and fields works the same way as on /studies:
curl "https://clinicaltrials.gov/api/v2/studies/NCT04852770?fields=NCTId,BriefTitle,OverallStatus"The response is the study object itself, not a list. An unknown but well-formed NCT number returns 404 with the text “NCT number NCT99999999 not found”, and a malformed one returns 400 “Parameter nctId has incorrect format”. If the number you send is an old alias of another study, the spec says you get a 301 redirect to the current record; requests follows it for you. Besides json, this endpoint takes format=csv, json.zip, fhir.json and ris.
Python example: page through results into a DataFrame
This script searches with any query.* and filter.* parameters, follows nextPageToken to the last page, flattens each study into one row and builds a pandas DataFrame. It needs requests and pandas.
import time
import requests
BASE_URL = "https://clinicaltrials.gov/api/v2"FIELDS = [ "NCTId", "BriefTitle", "OverallStatus", "Phase", "EnrollmentCount", "StartDate", "PrimaryCompletionDate", "LeadSponsorName",]
session = requests.Session()session.headers["User-Agent"] = "my-trials-script/1.0"
def search_studies(params, page_size=100, max_pages=None, pause=0.5): """Yield every study matching params, following nextPageToken.""" params = {**params, "fields": ",".join(FIELDS), "pageSize": page_size} pages = 0 while True: resp = session.get(f"{BASE_URL}/studies", params=params, timeout=30) if resp.status_code != 200: raise RuntimeError(f"{resp.status_code}: {resp.text[:200]}") body = resp.json() yield from body["studies"] pages += 1 token = body.get("nextPageToken") if not token or (max_pages and pages >= max_pages): return params["pageToken"] = token time.sleep(pause)
def flatten(study): """Pull the fields we asked for out of the nested study record.""" p = study["protocolSection"] ident = p["identificationModule"] status = p["statusModule"] design = p.get("designModule", {}) sponsor = p.get("sponsorCollaboratorsModule", {}).get("leadSponsor", {}) return { "nct_id": ident["nctId"], "title": ident.get("briefTitle"), "status": status.get("overallStatus"), "phases": "|".join(design.get("phases", [])), "enrollment": design.get("enrollmentInfo", {}).get("count"), "start": status.get("startDateStruct", {}).get("date"), "primary_completion": status.get("primaryCompletionDateStruct", {}).get("date"), "sponsor": sponsor.get("name"), }
if __name__ == "__main__": import pandas as pd
query = { "query.cond": "asthma", "query.spons": "AstraZeneca", "filter.overallStatus": "RECRUITING", } rows = [flatten(s) for s in search_studies(query)] df = pd.DataFrame(rows) print(len(df), "studies") print(df[["nct_id", "status", "phases", "enrollment", "start"]].head())Run on 2026-11-13 with page_size=5, it made five requests and returned 21 studies, matching the totalCount for the same query. Errors from the API are plain text, not JSON, which is why the script prints resp.text. The .get() calls matter: a study with no phase or no lead sponsor block would otherwise raise KeyError. Set max_pages while you develop a query so a broad search does not walk the whole registry.
Two more helpers built on the same session:
def count_studies(params): """Return the number of studies matching params, from one small request.""" resp = session.get( f"{BASE_URL}/studies", params={**params, "countTotal": "true", "pageSize": 1, "fields": "NCTId"}, timeout=30, ) resp.raise_for_status() return resp.json()["totalCount"]
resp = session.get( f"{BASE_URL}/studies/NCT04852770", params={"fields": "NCTId,BriefTitle,OverallStatus,EnrollmentCount"}, timeout=30,)if resp.status_code == 404: print("not found:", resp.text)else: resp.raise_for_status() print(resp.json()["protocolSection"]["statusModule"]["overallStatus"])ClinicalTrials.gov API rate limits
The v2 documentation publishes no rate limit: neither the OpenAPI spec nor the API page states a number, and the responses checked for this guide carried no rate-limit headers. Be polite anyway. Pause between pages (the script waits half a second), use a large pageSize with a short fields list rather than many small requests, cache results, and fetch again only after the weekday refresh shown by dataTimestamp.
The classic API retirement and what old code gets now
The classic ClinicalTrials.gov API was retired on June 25, 2024, together with the classic website. NLM announced API version 2.0 in its Technical Bulletin on March 19, 2024, and warned that the classic API “will be retired in June 2024”. The June 25 notice says the classic site and its API “are retired and no longer available”.
Old code now fails in one of two ways. A request to https://clinicaltrials.gov/api/query/full_studies or /api/query/study_fields returns HTTP 404 with an HTML “404 Not Found” page, which breaks any code that parses the body as JSON. A request to the old classic.clinicaltrials.gov host returns a 301 redirect to the same path on clinicaltrials.gov, which then returns that 404.
The migration guide maps each classic endpoint to its replacement; the parameter rows follow from the v2 parameter list in the spec:
| Classic API | API v2 |
|---|---|
/api/query/full_studies, /api/query/study_fields |
/api/v2/studies, with fields to pick fields |
expr= |
query.term= |
cond=, lead=, id= search options |
query.cond=, query.lead=, query.id= |
min_rnk, max_rnk |
pageSize and pageToken (no rank ranges) |
fmt=json or fmt=xml |
format=json or format=csv; no XML |
/ct2/show/{nctId}?displayxml=true or ?resultsxml=true |
/api/v2/studies/{nctId} |
/api/info/data_vrs |
/api/v2/version (dataTimestamp) |
/api/info/study_structure, /api/info/study_fields_list |
/api/v2/studies/metadata |
/api/info/search_areas |
/api/v2/studies/search-areas |
/api/query/field_values |
/api/v2/stats/field/values (all studies, at most 250 values, no search) |
The data model changed too. Field names are shorter, lists are plain arrays with plural names (conditions), dates are ISO 8601, formatted text is Markdown (set markupFormat=legacy for the old format), and many text fields became booleans or enums such as PHASE3. GET /studies/enums gives the classic value next to each new one.
If you cannot rewrite yet, the guide lists XML-only legacy endpoints under /api/legacy/, such as /api/legacy/study-fields, that take the classic parameters. That endpoint answered with classic-style XML on 2026-11-13, but it is a bridge, not a place to build new code: it returns XML only and, per the guide, at most the first 10,000 studies when expr is set.
Common ClinicalTrials.gov API errors
Most errors come back as a 400 or 404 with a short plain-text message that names the problem. All of these were returned by the live API on 2026-11-13:
| Status and message | Cause | Fix |
|---|---|---|
| 404 “NCT number NCT99999999 not found” | No study has that NCT number | Check the ID; search with filter.ids to catch aliases |
400 “Parameter nctId has incorrect format” |
The path is not an NCT number | Use the NCT prefix and digits, such as NCT04852770 |
400 “Invalid value in parameter overallStatus: OPEN” |
A status not in the enum | Use the upper-case values, such as RECRUITING |
| 400 “Parameter ‘fields’ contains invalid field name: ‘NotAField’” | A misspelled field name | Look the name up in /studies/metadata |
| 400 “Parameter ‘fields’ contains invalid CSV column name: ‘NCTId’” | JSON field names used with format=csv |
Use CSV column names, such as NCT Number |
| 404 HTML “404 Not Found” | A classic /api/query/ URL |
Move to /api/v2/studies |
When you need trials next to other sources
Hyperresearch reads ClinicalTrials.gov directly as one of its 120+ data sources, for teams that want trial evidence in a cited report rather than raw JSON. For another public data API walkthrough, see the FRED API in Python guide.
Sources
- ClinicalTrials.gov REST API, OpenAPI spec (version 2.0.5): https://clinicaltrials.gov/api/oas/v2
- ClinicalTrials.gov API page: https://clinicaltrials.gov/data-api/api
- API Migration Guide: https://clinicaltrials.gov/data-api/about-api/api-migration
- Study Data Structure: https://clinicaltrials.gov/data-api/about-api/study-data-structure
- Search Areas: https://clinicaltrials.gov/data-api/about-api/search-areas
- CSV Download: https://clinicaltrials.gov/data-api/about-api/csv-download
- Constructing Complex Search Queries: https://clinicaltrials.gov/find-studies/constructing-complex-search-queries
- API version endpoint: https://clinicaltrials.gov/api/v2/version
- NLM Technical Bulletin, “ClinicalTrials.gov API Version 2.0 Now Available” (2024-03-19): https://www.nlm.nih.gov/pubs/techbull/ma24/ma24_clinicaltrials_api.html
- NLM Technical Bulletin, “A Modern ClinicalTrials.gov Website” (2024-06-25): https://www.nlm.nih.gov/pubs/techbull/mj24/mj24_Modern_Clinical_Trials_Website.html
