Clinical Trials Database
Query ClinicalTrials.gov API v2 with correct filters and Essie expressions when validating health, biotech, or research products.
Overview
Clinical Trials Database is an agent skill most often used in Idea (also Validate) that documents ClinicalTrials.gov API v2 query, filter, and enum mechanics for accurate trial searches.
Install
npx skills add https://github.com/google-deepmind/science-skills --skill clinical-trials-databaseWhat is this skill?
- Documents REST v2 endpoints: `/studies`, single NCT lookup, metadata, enums, and search-areas
- Separates ranked query parameters (`query.cond`, `query.intr`, `query.term`, etc.) from exact filter parameters
- Covers `filter.overallStatus` and `filter.advanced` Essie expressions for phase, age group, study type, and sponsor
- Includes parameter aliases (`--condition`, `--intervention`, `--status`) for agent-friendly CLI-style invocation
- 5 documented `/studies` family endpoints
- 7 ranked query parameter areas plus structured filter parameters
Adoption & trust: 574 installs on skills.sh; 1.7k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need trustworthy clinical trial search syntax but trial registry APIs have dozens of fields and easy-to-mix query versus filter semantics.
Who is it for?
Indie builders researching medtech markets, building trial-alert products, or grounding agent answers in registry data.
Skip if: Clinical decision-making for patients or providers, or teams that need offline CSV dumps without calling the public API.
When should I use this skill?
User or task requires searching, filtering, or retrieving studies from ClinicalTrials.gov API v2.
What do I get? / Deliverables
Correctly structured API requests and filters so study lists and NCT lookups match recruitment status, interventions, and sponsor constraints you care about.
- Valid query and filter parameter sets
- Endpoint selection for list vs single-study vs metadata/enums
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Idea research is the primary shelf because builders first discover trial landscape, sponsors, and status before scoping a product. Research subphase fits structured literature and registry lookups that inform whether an opportunity is crowded or feasible.
Where it fits
List phase 3 trials for a target indication to see incumbent sponsors before choosing a feature set.
Filter by sponsor name to see how many active studies a competitor org runs in your geography.
Pull enum metadata so your MVP only promises fields the API actually exposes in v2.
How it compares
API field reference for agents, not a pre-built trial dashboard or MCP wrapper with cached studies.
Common Questions / FAQ
Who is clinical-trials-database for?
Solo founders and agent users building research, health, or data products who need ClinicalTrials.gov v2 parameters spelled out in one skill.
When should I use clinical-trials-database?
In Idea research to map competitors and trial density; in Validate scope to cite active studies for a condition; in Build integrations when wiring search UI to `/studies` and metadata endpoints.
Is clinical-trials-database safe to install?
The skill is documentation for a public government API; review the Security Audits panel on this Prism page and treat outbound trial data like any third-party API in your agent policy.
SKILL.md
READMESKILL.md - Clinical Trials Database
# 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 with