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 .licenses/clinical_trials_database_LICENSE.txt does not already exist in the workspace root 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.