Clinical Trials Database

Clinical Trials Database

Prerequisites

1. `uv`: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH. 2. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://clinicaltrials.gov/, then (2) create the file recording the notification text and timestamp.

Overview

Access worldwide clinical trial data from ClinicalTrials.gov via the REST API v2. The CLI script at scripts/clinical_trials_api.py wraps the API with dedicated flags for common filters (phase, age group, status, intervention, sponsor, etc.) so you rarely need to construct raw queries.

Core Rules

• Use the Wrapper: ALWAYS execute the provided helper scripts to query the

database rather than accessing the database directly. The scripts automatically enforce the required rate limit gracefully.

• Always use `--fields` — trial JSON records can be very large; restrict

to the data points you need.

• Use `--count-total` first — check result volume before fetching all

records.

• Paginate large result sets — use --limit with --page-token to

iterate.

• Trust Search Filters: Do not manually re-filter results unless

explicitly asked to verify detailed eligibility.

• Notification: If this skill is used, ensure this is mentioned in the

output.

Context Efficiency Warning

Trial JSON records can be very large. Always use the --fields parameter to restrict the response to only the data points you need. After writing to file, read only the fields you need rather than the entire file.

[!TIP] Use references/studies_schema.md to identify exact field paths for

--fields.

Response Layout Summary

API responses contain a list of studies (usually in a studies[] array). Each study is split into protocolSection and optional resultsSection.

[!Tip] Use the shorthand aliases below with the --fields parameter to

request specific data and keep responses small.

Top-Level Fields

• totalCount — Total studies matching query (integer)
• studies[] — Array of study objects
• nextPageToken — cursor string for pagination

Common Study Fields (and shorthand alias)

• Identification
• protocolSection.identificationModule.nctId (NCTId) — Unique trial ID
• protocolSection.identificationModule.briefTitle (BriefTitle) — Short

title

• Status
• protocolSection.statusModule.overallStatus (OverallStatus) —

Recruitment status

• Description
• protocolSection.descriptionModule.briefSummary (BriefSummary) —

Short description

• Arms & Interventions
• protocolSection.armsInterventionsModule.interventions

(ArmsInterventionsModule)

• Eligibility
• protocolSection.eligibilityModule.eligibilityCriteria

(EligibilityCriteria) — Inclusion/Exclusion

• protocolSection.eligibilityModule.stdAges (StdAge) — CHILD, ADULT,

etc.

Consult references/studies_schema.md for full paths (Locations, Outcomes, Results) and common --fields recipes.

Commands

Search for studies

Use for: finding trials by disease, drug, phase, status, age group, or any combination of these filters.

uv run scripts/clinical_trials_api.py search \
  --condition "<disease>" \
  --intervention "<drug_or_treatment>" \
  --status "<status>" \
  --phase "<phase>" \
  --age-group "<age_group>" \
  --study-type "<study_type>" \
  --sponsor "<sponsor_name>" \
  --has-results \
  --sort "<field>:<asc|desc>" \
  --fields "<fields>" \
  --limit <N> \
  --count-total \
  --page-token "<token>" \
  --output /tmp/search_results.json

All flags are optional and combine via AND logic.

Flag reference:

• --condition — Disease or condition to search for (e.g. `"cystic

fibrosis"`).

• --intervention — Drug, device, or treatment name (e.g. "pembrolizumab").
• --status — Recruitment status filter. Values: RECRUITING, COMPLETED,

NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION, TERMINATED, SUSPENDED, WITHDRAWN.

• --phase — Trial phase filter. Values: PHASE1, PHASE2, PHASE3, PHASE4,

EARLY_PHASE1, NA.

• --age-group — Patient age group filter. Values: CHILD (0–17), ADULT

(18–64), OLDER_ADULT (65+).

• --study-type — Type of study. Values: INTERVENTIONAL, OBSERVATIONAL,

EXPANDED_ACCESS.

• --sponsor — Lead sponsor or institution name (e.g. `"National Cancer

Institute"`).

• --has-results — Boolean flag (no value needed). When present, filters for

studies that have results available on ClinicalTrials.gov.

• --sort — Sort order as FieldName:asc or FieldName:desc. Common fields:

LastUpdatePostDate, EnrollmentCount, StudyFirstPostDate, StartDate.

• --fields — Comma-separated list of JSON field names to include in the

response. Use this to keep responses small (e.g. "NCTId,BriefTitle,OverallStatus,Phase"). See references/studies_schema.md for available field paths.

• --limit — Maximum number of studies to return per request (1–1000, default

10).

• --count-total — Boolean flag (no value needed). When present, the response

includes a totalCount field showing the total number of matching studies across all pages.

• --page-token — An opaque cursor string used to fetch the next page of

results. Obtain this value from the nextPageToken field in a previous search response. Do not construct this string yourself; always copy it verbatim from the API response. See the Pagination section below.

• --advanced — Raw Essie filter expression for structured queries beyond the

dedicated flags (e.g. "AREA[LocationCountry]United States"). Combined with other flags via AND. See references/clinical_trials_api.md for syntax.

• --output — (Required) File path where the JSON response is written.

Example — actively recruiting Phase 3 pediatric cystic fibrosis trials:

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --phase PHASE3 \
  --age-group CHILD \
  --fields "NCTId,BriefTitle,OverallStatus,Phase" \
  --limit 10 \
  --output /tmp/cf_trials.json

Example — recruiting atezolizumab trials for esophageal cancer:

uv run scripts/clinical_trials_api.py search \
  --condition "esophageal cancer" \
  --intervention "Atezolizumab" \
  --status RECRUITING \
  --fields "NCTId,BriefTitle,Phase" \
  --limit 10 \
  --output /tmp/atezolizumab_trials.json

Retrieve a study by NCT ID

Use for: fetching full details of a specific trial when you already have the NCT identifier.

uv run scripts/clinical_trials_api.py get-study \
  <nct_id> [--fields "<fields>"] \
  --output /tmp/study.json

Returns a useful default set of fields if --fields is omitted: NCTId,BriefTitle,OverallStatus,Phase,BriefSummary, ConditionsModule,ArmsInterventionsModule,EligibilityModule

Structure of the default response:

{
  "protocolSection": {
    "identificationModule": {
      "nctId": "NCT00000000",
      "briefTitle": "Study Title"
    },
    "statusModule": {
      "overallStatus": "RECRUITING"
    },
    "descriptionModule": {
      "briefSummary": "This study is about..."
    },
    "conditionsModule": {
      "conditions": [ "Condition Name" ]
    },
    "armsInterventionsModule": {
      "interventions": [ { "type": "DRUG", "name": "Drug Name" } ]
    },
    "eligibilityModule": {
      "eligibilityCriteria": "Inclusion:\n- ...",
      "stdAges": [ "ADULT" ]
    }
  }
}

Get eligibility / inclusion criteria

Use for: pulling inclusion/exclusion rules, age ranges, and sex requirements for patient-matching tasks.

uv run scripts/clinical_trials_api.py \
  get-eligibility <nct_id> \
  --output /tmp/eligibility.json

Shortcut that returns title and the full eligibility module (inclusion/exclusion criteria, age range, sex).

Example — inclusion criteria for NCT04886804:

uv run scripts/clinical_trials_api.py \
  get-eligibility NCT04886804 \
  --output /tmp/eligibility_NCT04886804.json

Count matching studies

Use for: exploring the trial landscape — checking how many trials exist for a condition, phase, or status before fetching full records.

uv run scripts/clinical_trials_api.py count \
  --condition "<disease>" \
  [--status "<status>"] [--phase "<phase>"] ... \
  --output /tmp/count.json

Returns only the total count of clinical trials matching the search criteria without fetching study records. Accepts the same filter flags as search.

Search by location / geography

Use for: narrowing trials to a specific country, state, or city.

Use --advanced with AREA[LocationCountry] or AREA[LocationCity] to restrict results by geography:

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --advanced "AREA[LocationCity]New York" \
  --fields "NCTId,BriefTitle" \
  --limit 20 \
  --output /tmp/nyc_cf_trials.json

Search by sponsor / organization

Use for: identifying a sponsor's or institution's trial portfolio.

Use --sponsor to find trials run by a specific institution or company:

uv run scripts/clinical_trials_api.py search \
  --sponsor "National Cancer Institute" \
  --fields "NCTId,BriefTitle,LeadSponsorName" \
  --limit 20 \
  --output /tmp/nci_trials.json

Combined multi-criteria search

Use for: complex queries that layer multiple filters (condition and drug and phase and geography and sponsor, etc.).

All flags combine via AND, so you can layer conditions, interventions, status, phase, geography, and sponsor in a single query:

uv run scripts/clinical_trials_api.py search \
  --condition "pancreatic cancer" \
  --intervention "immunotherapy" \
  --status RECRUITING \
  --phase PHASE3 \
  --advanced "AREA[LocationCountry]United States" \
  --fields "NCTId,BriefTitle,Phase,LeadSponsorName" \
  --limit 20 \
  --output /tmp/panc_trials.json

Raw API query (escape hatch)

Use for: uncommon endpoints or parameter combinations not covered by the dedicated flags.

uv run scripts/clinical_trials_api.py raw-query \
  --endpoint <path> \
  --params '<json_dict>' \
  --output /tmp/raw_result.json

Pagination

When results exceed --limit, the response includes a nextPageToken. Pass it with --page-token to fetch the next page:

uv run scripts/clinical_trials_api.py search \
  --condition "breast cancer" \
  --status RECRUITING \
  --limit 50 --count-total \
  --output /tmp/breast_cancer_p1.json

uv run scripts/clinical_trials_api.py search \
  --condition "breast cancer" \
  --status RECRUITING \
  --limit 50 --page-token "CAo=" \
  --output /tmp/breast_cancer_p2.json

Advanced Querying

For complex filtering beyond the dedicated flags, use --advanced with an Essie expression.

What is an Essie Expression? Essie is the search engine powering ClinicalTrials.gov. An Essie expression is a structured query that targets specific fields (e.g., country, phase) rather than doing general keyword searches.

• `AREA[Field]Value`: Targets a specific field.
• AREA[LocationCountry]United States
• AREA[Phase]PHASE3
• Boolean operators: Combine with AND, OR, NOT.
• `RANGE[min, max]`: For numeric/date fields (e.g. RANGE[500, MAX]).

See references/clinical_trials_api.md for syntax and available fields.

It is combined with other flags via AND:

uv run scripts/clinical_trials_api.py search \
  --condition "diabetes" \
  --advanced "AREA[LocationCountry]United States \
    AND AREA[EnrollmentCount]RANGE[500, MAX]" \
  --fields "NCTId,BriefTitle,EnrollmentCount" \
  --output /tmp/diabetes_us_large.json

References

• API parameters, enum values, and Essie syntax:

references/clinical_trials_api.md

• JSON field paths and `--fields` recipes: references/studies_schema.md

ClinicalTrials.gov API v2 Reference

This document covers the querying mechanics, parameter reference, valid enum values, and advanced expression syntax for the ClinicalTrials.gov REST API v2.

Endpoints

• /studies — GET — Search and filter studies, returns paginated list
• /studies/{nctId} — GET — Retrieve a single study by NCT ID
• /studies/metadata — GET — List all available data fields
• /studies/enums — GET — List all enum types and valid values
• /studies/search-areas — GET — List searchable field areas

Query Parameters

Query parameters perform ranked text searches. They influence the relevance ordering of results.

• query.cond (--condition) — Condition or disease
• query.intr (--intervention) — Intervention or treatment (drug, device,

etc.)

• query.term (--term) — General search across all text fields (57 fields)
• query.titles (--title) — Study titles and acronyms
• query.locn (--location) — Location-related fields (city, state, country,

facility)

• query.spons (--sponsor) — Sponsor or collaborator name
• query.id (--id) — Study identifiers (NCT ID, org study ID)

Filter Parameters

Filter parameters perform exact matching and do not affect relevance ranking.

• filter.overallStatus (--status) — Recruitment status (comma-separated)
• filter.advanced (--advanced / --phase / --age-group / --study-type /

--sponsor) — Essie expression for structured filtering

• filter.ids — Restrict to specific NCT IDs
• filter.geo — Distance-based geographic filter

Control Parameters

• fields (--fields) — Comma-separated list of fields to return
• pageSize (--limit) — Results per page (1–1000, default 10)
• pageToken (--page-token) — Token for the next page of results
• countTotal (--count-total) — If true, response includes totalCount
• sort (--sort) — Sort field and direction, e.g. LastUpdatePostDate:desc
• format — Response format: json (default) or csv

Sortable Fields

Common sortable fields: LastUpdatePostDate, NumericChange, EnrollmentCount, StudyFirstPostDate, StartDate.

Format: FieldName:asc or FieldName:desc.

Valid Enum Values

Recruitment Status (filter.overallStatus)

• RECRUITING — Currently enrolling participants
• NOT_YET_RECRUITING — Approved but not yet enrolling
• ACTIVE_NOT_RECRUITING — Ongoing but no longer enrolling
• ENROLLING_BY_INVITATION — Enrolling by invitation only
• COMPLETED — Study finished
• SUSPENDED — Temporarily halted
• TERMINATED — Stopped early
• WITHDRAWN — Pulled before enrollment

Phase

• EARLY_PHASE1 — Early Phase 1 (formerly Phase 0)
• PHASE1 — Phase 1
• PHASE2 — Phase 2
• PHASE3 — Phase 3
• PHASE4 — Phase 4 (post-marketing)
• NA — Not Applicable

Standard Age Group (StdAge)

• CHILD — Birth to 17 years
• ADULT — 18 to 64 years
• OLDER_ADULT — 65+ years

Study Type

• INTERVENTIONAL — Tests a treatment or intervention
• OBSERVATIONAL — Observes outcomes without intervention
• EXPANDED_ACCESS — Treatment use outside of clinical trials

Sex

• ALL — All sexes eligible
• MALE — Males only
• FEMALE — Females only

Essie Expression Syntax (for filter.advanced)

The filter.advanced parameter accepts Essie expressions for structured, non-ranked filtering.

AREA Operator

Target a specific field: AREA[FieldName]Value

Examples:

• AREA[Phase]PHASE3 — Phase 3 trials only
• AREA[StdAge]CHILD — Trials accepting pediatric patients
• AREA[StudyType]INTERVENTIONAL — Interventional studies only
• AREA[LeadSponsorName]Pfizer — Sponsored by Pfizer
• AREA[LocationCountry]United States — Located in the US
• AREA[Sex]FEMALE — Female-only trials

Boolean Operators

Combine clauses with AND, OR, NOT:

• AREA[Phase]PHASE3 AND AREA[StdAge]CHILD
• AREA[Phase]PHASE2 OR AREA[Phase]PHASE3
• NOT AREA[StudyType]OBSERVATIONAL

RANGE Operator

Filter date or numeric fields within a range:

• AREA[StartDate]RANGE[01/01/2023, MAX] — Started on or after Jan 1, 2023
• AREA[EnrollmentCount]RANGE[100, 500] — Enrollment between 100 and 500
• AREA[CompletionDate]RANGE[MIN, 12/31/2025] — Completing before end of 2025

Use MIN and MAX for open-ended boundaries.

Response Data Structure

Study records are organised into hierarchical modules:

protocolSection

• identificationModule — NCT ID, titles, organisation
• statusModule — overall status, start / completion dates, last update
• sponsorCollaboratorsModule — lead sponsor, collaborators, responsible

party

• descriptionModule — brief summary, detailed description
• conditionsModule — conditions under study
• designModule — study type, phases, enrolment info
• armsInterventionsModule — study arms and interventions
• outcomesModule — primary and secondary outcomes
• eligibilityModule — inclusion / exclusion criteria, age / sex requirements
• contactsLocationsModule — contacts and site locations
• referencesModule — citations and links

derivedSection

• conditionBrowseModule — MeSH terms for conditions
• interventionBrowseModule — MeSH terms for interventions

resultsSection (when available)

• participantFlowModule — participant flow
• baselineCharacteristicsModule — baseline data
• outcomeMeasuresModule — outcome results
• adverseEventsModule — adverse events

hasResults

Boolean flag indicating whether results have been posted for the study.

Pagination

When results exceed the page size, the response includes a nextPageTokenfield. Pass this token via the pageToken parameter (or --page-token flag) to fetch the next page. The final page omits this token.

Response shape for multi-study queries:

{
  "totalCount": 1234,
  "studies": [...],
  "nextPageToken": "CAo="
}

Data Standards

• Dates — ISO 8601 structured objects,

e.g. {"date": "2024-03-15", "type": "ACTUAL"}

• Rich text — descriptive fields use CommonMark Markdown
• Enums — status, phase, study type, and similar fields use standardised

enumerated values (not free text)

ClinicalTrials.gov Study Data Schema

This reference documents the JSON structure and field paths returned by the ClinicalTrials.gov API v2. Use these paths with the --fields parameter to select specific data.

Top-Level Response

Multi-study query (/studies):

• totalCount — integer (present when countTotal=true)
• studies[] — array of study objects
• nextPageToken — string (omitted on final page)

Single-study query (/studies/{nctId}): returns a study object directly.

Study Object Structure

Each study has two major sections: protocolSection and resultsSection, plus a hasResults boolean.

Protocol Section

Identification Module

• protocolSection.identificationModule.nctId (NCTId)

— Unique trial identifier

• protocolSection.identificationModule.briefTitle (BriefTitle)

— Short public title

• protocolSection.identificationModule.officialTitle (OfficialTitle)

— Full scientific title

• protocolSection.identificationModule.organization.fullName (Organization)

— Sponsoring organization

Status Module

• protocolSection.statusModule.overallStatus (OverallStatus)

— Recruitment status. Values: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION, COMPLETED, SUSPENDED, TERMINATED, WITHDRAWN

• protocolSection.statusModule.startDateStruct.date (StartDate)

— Study start date

• protocolSection.statusModule.primaryCompletionDateStruct.date

(PrimaryCompletionDate) — Primary outcome completion

• protocolSection.statusModule.completionDateStruct.date (CompletionDate)

— Full study completion

• protocolSection.statusModule.lastUpdatePostDateStruct.date

(LastUpdatePostDate) — Last record update

Sponsor/Collaborators Module

• protocolSection.sponsorCollaboratorsModule.leadSponsor.name

(LeadSponsorName) — Lead sponsor

Description Module

• protocolSection.descriptionModule.briefSummary (BriefSummary)

— Short study description

• protocolSection.descriptionModule.detailedDescription

(DetailedDescription) — Extended scientific description

Conditions Module

• protocolSection.conditionsModule.conditions (ConditionsModule)

— Conditions module (includes array of diseases)

• protocolSection.conditionsModule.keywords (Keywords)

— Categorization terms

Design Module

• protocolSection.designModule.studyType (StudyType)

— INTERVENTIONAL, OBSERVATIONAL, or EXPANDED_ACCESS

• protocolSection.designModule.phases (Phase)

— Array: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA

• protocolSection.designModule.enrollmentInfo.count (EnrollmentCount)

— Participant count (actual or estimated)

Arms & Interventions Module

• protocolSection.armsInterventionsModule.armGroups (ArmGroup)

— Trial arms with labels and descriptions

• protocolSection.armsInterventionsModule.interventions

(ArmsInterventionsModule) — Arms and treatments (DRUG, DEVICE, etc.)

Outcomes Module

• protocolSection.outcomesModule.primaryOutcomes (PrimaryOutcome)

— Primary endpoints

• protocolSection.outcomesModule.secondaryOutcomes (SecondaryOutcome)

— Secondary endpoints

Eligibility Module

• protocolSection.eligibilityModule.eligibilityCriteria

(EligibilityCriteria) — Full inclusion/exclusion text

• protocolSection.eligibilityModule.sex (Sex) — ALL, MALE, or FEMALE
• protocolSection.eligibilityModule.minimumAge (MinimumAge)

— e.g. "18 Years"

• protocolSection.eligibilityModule.maximumAge (MaximumAge)

— e.g. "65 Years"

• protocolSection.eligibilityModule.healthyVolunteers (HealthyVolunteers)

— Boolean

• protocolSection.eligibilityModule.stdAges (StdAge)

— Array: CHILD, ADULT, OLDER_ADULT

To retrieve just the eligibility module, use: --fields "NCTId,BriefTitle,EligibilityModule" or the get-eligibility command.

Contacts & Locations Module

• protocolSection.contactsLocationsModule.centralContacts (CentralContact) —

Primary contact persons

• protocolSection.contactsLocationsModule.locations (LocationFacility) —

Facilities with city, state, country, and status

Results Section

Available when hasResults is true.

• Participant Flow Module — Participant counts per study period
• Baseline Characteristics Module — Demographics and baseline data
• Outcome Measures Module — Statistical results for primary/secondary

outcomes

• Adverse Events Module — Serious and other adverse event data

Common --fields Recipes

• Overview:

NCTId,BriefTitle,OverallStatus,Phase,ConditionsModule

• Eligibility details:

NCTId,BriefTitle,EligibilityModule

• Interventions:

NCTId,BriefTitle,ArmsInterventionsModule

• Locations:

NCTId,ContactsLocationsModule

• Outcomes:

NCTId,PrimaryOutcome,SecondaryOutcome

• Sponsor info:

NCTId,BriefTitle,LeadSponsorName,Organization

• Full protocol summary:

NCTId,BriefTitle,OverallStatus,Phase,BriefSummary,ConditionsModule, ArmsInterventionsModule,EligibilityModule