NewAnswers MCP: one question, one checked answer for your agent.See how it works

Guides

ClinicalTrials.gov API v2: query studies, fields and paging (with Python)

By , founder of HyperresearchPublished

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:

Terminal window
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:

Terminal window
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, pageSize and pageToken.
  • Stop on the token, not on an empty list. A page may come back with an empty studies array before the end.
  • Count once. countTotal is 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:

Terminal window
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:

Terminal window
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