Raw schema
{
"type": "object",
"properties": {
"query": {
"description": "General free-text search across all fields. Runs the 57-field relevance search ClinicalTrials.gov publishes for this parameter β NCTId, NCTIdAlias, OrgStudyId, SecondaryId, Acronym, BriefTitle, OfficialTitle, Condition, InterventionName, InterventionOtherName, Phase, StdAge, StudyType, BriefSummary, outcome measures and their descriptions, LeadSponsorName, CollaboratorName, the Location* fields, the Design* fields, and the ConditionAncestorTerm/InterventionAncestorTerm MeSH umbrellas β so a hit need not carry your term in the field you had in mind. Plain words plus AND, OR, NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression β those work here as well as in advancedFilter, so AREA[Phase]PHASE2 is accepted in this parameter; a stray bracket fails. `( )` group sub-expressions and work when matched; `,` acts as AND. The dedicated *Query parameters (conditionQuery, interventionQuery, etc.) scope a search to one field.",
"type": "string"
},
"conditionQuery": {
"description": "Condition/disease-specific search. E.g., \"Type 2 Diabetes\", \"non-small cell lung cancer\". Matches Condition, BriefTitle, OfficialTitle, ConditionMeshTerm, ConditionAncestorTerm, Keyword, and NCTId. ConditionAncestorTerm is the MeSH umbrella above the conditions a study itself lists, so results run broader than those lists β a study can match a parent term it never names. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
"type": "string"
},
"interventionQuery": {
"description": "Intervention/treatment search. E.g., \"pembrolizumab\", \"cognitive behavioral therapy\". Matches InterventionName, InterventionType, ArmGroupType, InterventionOtherName, BriefTitle, OfficialTitle, ArmGroupLabel, InterventionMeshTerm, Keyword, InterventionAncestorTerm, InterventionDescription, and ArmGroupDescription. InterventionAncestorTerm is the MeSH umbrella above the interventions a study itself lists, so results run broader than those lists. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
"type": "string"
},
"locationQuery": {
"description": "Location search β city, state, country, or facility name. Matches LocationCity, LocationState, LocationCountry, LocationFacility, and LocationZip; a study matches when any of its sites does. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
"type": "string"
},
"sponsorQuery": {
"description": "Sponsor/collaborator name search. Matches LeadSponsorName, CollaboratorName, and OrgFullName. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
"type": "string"
},
"titleQuery": {
"description": "Search within study titles and acronyms only. Matches Acronym, BriefTitle, and OfficialTitle. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
"type": "string"
},
"outcomeQuery": {
"description": "Search within outcome measure fields. Matches PrimaryOutcomeMeasure, SecondaryOutcomeMeasure, OtherOutcomeMeasure, and OutcomeMeasureTitle, plus their description counterparts PrimaryOutcomeDescription, SecondaryOutcomeDescription, OtherOutcomeDescription, OutcomeMeasureDescription, and OutcomeMeasurePopulationDescription β so a term appearing only in outcome prose still matches. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
"type": "string"
},
"statusFilter": {
"description": "Filter by study status. Omit to search all statuses β an empty list is rejected, not treated as \"no filter\". Values: RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION, SUSPENDED, TERMINATED, WITHDRAWN, UNKNOWN, WITHHELD, NO_LONGER_AVAILABLE, AVAILABLE, APPROVED_FOR_MARKETING, TEMPORARILY_NOT_AVAILABLE.",
"anyOf": [
{
"type": "string",
"description": "A single status value."
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "Multiple status values (OR)."
}
]
},
"phaseFilter": {
"description": "Filter by trial phase. Omit to search all phases β an empty list is rejected, not treated as \"no filter\". Values: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA. Case and spacing variants (\"Phase 3\", \"early phase 1\", \"Not Applicable\") are accepted, and a list or a comma- or pipe-joined string matches any of the phases. Each entry must name a phase β put search expressions (OR, NOT, AREA[β¦]) in advancedFilter.",
"anyOf": [
{
"type": "string",
"description": "A single phase value."
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "Multiple phase values (OR)."
}
]
},
"advancedFilter": {
"description": "Advanced filter using AREA[FieldName]value syntax. Examples: \"AREA[StudyType]INTERVENTIONAL\", \"AREA[EnrollmentCount]RANGE[100, 1000]\", \"AREA[Phase]PHASE2 AND AREA[StudyType]INTERVENTIONAL\", \"(AREA[Phase]PHASE3 OR AREA[Phase]PHASE4) AND AREA[StudyType]INTERVENTIONAL\". \"AREA[HasResults]true\" restricts to studies with posted results. AND/OR/NOT join complete AREA[FieldName]value expressions; parentheses group them. Call clinicaltrials_get_field_definitions to find AREA[]-compatible field names. A field name β a record field, an index-only piece such as NumLocations, or a search area such as ConditionSearch β that differs from the spelling AREA[] accepts only by case (AREA[overallstatus]) is corrected before the request, here and in the query parameters, and searchCriteria shows the expression as sent.",
"type": "string"
},
"geoFilter": {
"description": "Geographic proximity filter. Format: distance(lat,lon,radius), where radius carries a `mi` or `km` suffix β e.g. \"distance(47.6062,-122.3321,50mi)\" for studies within 50 miles of Seattle. The suffix is required: a radius with no unit is rejected, as are a non-positive radius, a latitude outside [-90, 90], and a longitude outside [-180, 180]. When set, each study's locations are re-sorted by proximity to the center so the nearest matched site leads, annotated with its distance in miles; the full location list is preserved.",
"type": "string"
},
"nctIds": {
"description": "Filter to specific NCT IDs for batch lookups. Omit to search every study β an empty list is rejected, not treated as \"no filter\". Repeated IDs collapse to one, first occurrence kept. One request carries as many leading IDs as fit ClinicalTrials.gov's URL length limit beside the other parameters β about 560 when nothing else is set, fewer beside long queries or field lists β and the rest come back unqueried in deferredNctIds, in order, for a follow-up call; every page of a walk queries the same IDs. A list over 1000 entries, repeats included, is rejected. Supplying this lifts the default unknown-enrollment exclusion, so an ID you name is never filtered out of its own lookup.",
"anyOf": [
{
"type": "string",
"pattern": "^NCT\\d{8}$",
"description": "A single NCT ID."
},
{
"type": "array",
"items": {
"type": "string",
"pattern": "^NCT\\d{8}$"
},
"maxItems": 1000,
"description": "Multiple NCT IDs (OR), at most 1000 entries counting repeats."
}
]
},
"fields": {
"description": "PascalCase piece names to return, leaves or groups (a group such as StatusModule returns all of its fields); strongly recommended since full records are ~70KB. Omit for the compact index projection β an empty list is rejected, not treated as omission. A comma- or pipe-joined entry (\"NCTId,BriefTitle\") is split into separate names, and a full path as clinicaltrials_get_field_definitions prints it (\"protocolSection.statusModule.overallStatus\") is sent as its piece name. Common leaves: NCTId, BriefTitle, BriefSummary, OverallStatus, Phase, LeadSponsorName, Condition. Call clinicaltrials_get_field_definitions with a concept query (e.g., \"adverse events\", \"eligibility\") to find the exact leaf for any concept. Naming ResultsSection, or a module or group under it (OutcomeMeasuresModule, AdverseEventsModule), caps the page at 10 studies, since one record with posted results can run past 1 MB; a leaf under it (OutcomeMeasureTitle) keeps the server's usual cap.",
"type": "array",
"items": {
"type": "string"
}
},
"sort": {
"description": "Sort order. Format: FieldName:asc or FieldName:desc. E.g., \"LastUpdatePostDate:desc\", \"EnrollmentCount:desc\". Max 2 fields comma-separated. Only date and numeric fields sort β those whose clinicaltrials_get_field_definitions type is NormalizedDate, PartialDate, DateTimeMinutes, integer, long, or short β plus \"@relevance\", which ranks by match to the query; a bare \"relevance\" is sent as \"@relevance\". For \"largest trials\" queries, pair EnrollmentCount:desc with advancedFilter \"AREA[StudyType]INTERVENTIONAL\" β the top enrollment counts are observational registry/claims studies enrolling tens of millions. Enrollment counts are sponsor-reported and not validated upstream beyond the unknown-enrollment sentinel exclusion.",
"type": "string"
},
"pageSize": {
"default": 10,
"description": "Results per page. Default 10; a larger value returns at most this server's per-page cap (200 unless the operator changed it; 10, or the operator's cap if lower, when fields names ResultsSection or a module or group under it, or cannot be checked for one) and says so in truncated/shown/cap, with nextPageToken to page the rest. The cap sits below ClinicalTrials.gov's own page maximum of 1000 because full study records run to tens of KB each, and one with posted results can run past 1 MB.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"pageToken": {
"description": "Pagination cursor: a previous response's nextPageToken, passed back unchanged with the same criteria. Tokens expire when ClinicalTrials.gov refreshes its data.",
"type": "string"
},
"countTotal": {
"default": true,
"description": "Include total study count in response. Only computed on the first page.",
"type": "boolean"
},
"includeUnknownEnrollment": {
"default": false,
"description": "Include studies whose EnrollmentCount is the upstream \"unknown\" sentinel (99999999). Excluded by default β the sentinel pollutes RANGE[N, MAX] queries and EnrollmentCount:desc sorts. Set true for data-quality audits or when targeting unknown-enrollment studies specifically.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}