Construct GET request to https://clinicaltrials.gov/api/v2/studies with query parameters: query.cond (condition/disease), query.intr (intervention), pageSize (max 1000), and optional sort field
Parse the JSON response envelope: studies array contains objects with protocolSection, derivedSection, and hasResults boolean; capture nextPageToken from the response root
Iterate pages by passing the nextPageToken value as the pageToken parameter in subsequent requests until nextPageToken is absent
Extract nested fields from protocolSection (identificationModule for NCT ID and title, statusModule for overall status and phase, eligibilityModule for criteria text) using the published study data structure schema at clinicaltrials.gov/data-api/about-api/study-data-structure
For a single full record, call GET https://clinicaltrials.gov/api/v2/studies/{nctId} to retrieve resultsSection including participant flow and adverse events when hasResults is true
Validate enumerated status values (RECRUITING, COMPLETED, TERMINATED, etc.) against the API schema rather than hardcoding strings, as the v2 schema enforces controlled vocabulary
Known gotchas
The v1 API (classic.clinicaltrials.gov) was retired; all new integrations must use the v2 base URL at clinicaltrials.gov/api/v2 — do not reference legacy endpoints
pageSize is capped at 1000 per request; requesting a higher value will return an error rather than silently truncating
Free-text query parameters (query.term, query.cond) use NLM's full-text search semantics, not SQL LIKE; field-level filters use the fields parameter with dot-notation paths from the schema
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp