# 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](https://clinicaltrials.gov/api/oas/v2) (API version 2.0.5) and the [API Migration Guide](https://clinicaltrials.gov/data-api/about-api/api-migration), 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](https://clinicaltrials.gov/data-api/api) 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:

```bash
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:

```bash
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](https://clinicaltrials.gov/data-api/about-api/csv-download).

## 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:

```bash
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`:

```bash
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`.

```python
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:

```python
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](https://www.nlm.nih.gov/pubs/techbull/ma24/ma24_clinicaltrials_api.html) on March 19, 2024, and warned that the classic API "will be retired in June 2024". The [June 25 notice](https://www.nlm.nih.gov/pubs/techbull/mj24/mj24_Modern_Clinical_Trials_Website.html) 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](/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](/guides/fred-api-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
