ClinicalTrials.gov API Migration: Classic to v2

What happens to the old URLs?

The classic hostname redirects requests to the matching path on the modern domain, but that doesn't "revive" the retired route. For example, a request to a classic study_fields endpoint may redirect first and then land on a 404. Old website search URLs can redirect to the modern search experience, but that's not the same thing as getting an API response.

If something started failing around mid-2024, don't start with credentials or network debugging. Check the final HTTP status code and the response body. Also be aware that some clients hide the first redirect - so the final 404 can look like a mysterious endpoint failure when it's really "redirect + dead route."

What replaces the classic service?

The current API lives under /api/v2/. The main study-search endpoint is /api/v2/studies. By default it returns complete study records; if you pass fields, it returns only the fields you request. You can retrieve a single study by NCT number, and there are separate endpoints for metadata, field statistics, search areas, version information, and bulk downloads.

NLM also provides /api/legacy/ endpoints meant to reproduce parts of the classic API behavior. They can help if you have an existing system that can't switch from the classic XML shape immediately. They aren't a way to keep calling the old /api/query/ routes, and you still need a v2 migration plan.

Endpoint mapping

For field values, the stats endpoint gives you values across the registry, capped at 250 values. Pick the endpoint based on what you're trying to answer: metadata tells you what fields exist, field-value statistics help you inspect candidate values, and study search returns matching records.

Parameter mapping

In classic, rank ranges were part of the request. In v2, you don't convert that into "page 3." Instead, v2 returns a page and may include nextPageToken. To fetch the next page, pass that token back as pageToken on the next request. Default page size is 10; maximum is 1,000.

A minimal search request might look like this:

/api/v2/studies?query.term=heart%20attack&fields=NCTId,BriefTitle&pageSize=100&countTotal=true

The studies array holds the records. If the response includes nextPageToken, keep requesting pages until there's no next token left. Don't build later pages by guessing a rank offset - v2's cursor works differently.

Check result ordering before you switch

Even when you get the same studies back, the order can change. In a live comparison using heart attack, the classic-style legacy response and v2 returned the same total count but different first results. Adding sort=@relevance to the v2 request brought the first three results into line with the legacy response in that test.

That's not a blanket guarantee that every query will match rankings. For queries that power user-facing lists, saved searches, or scheduled exports, compare both membership and order. If order matters, set it explicitly and test representative queries.

Fields are nested inside modules

In v2, records are structured around protocolSection and other sections. For example, the NCT identifier is at protocolSection.identificationModule.nctId instead of a top-level NCTId field. The field name you request might look familiar, but its location in the response changes.

Use the NLM Study Data Structure documentation to map the fields your application actually consumes. Build a field-by-field mapping for your parser and downstream storage, especially if you only request a subset with fields. And don't assume every record has every selected field - handle missing or null values explicitly.

Lists, enums, and dates use different conventions

List fields are returned as plain arrays, without the wrapper objects some classic responses used. You may also see pluralized names like conditions and phases. Code that expects a single object or reads values from a legacy wrapper will need changes.

Enum values use uppercase codes (for example, RECRUITING, PHASE2, and NA) rather than display labels like "Recruiting," "Phase 2," and "Not Applicable." The /api/v2/studies/enums endpoint provides values alongside legacy values. If you need the old labels in a UI or you're reconciling historical data, use that mapping.

Dates come back in ISO 8601 formats, with precision varying by field (year only, year+month, full date, or date+time). Legacy display strings like "June 2020" shouldn't be treated as the canonical stored representation. v2 also includes boolean fields for some "unknown" cases that were previously expressed differently, including SubmissionUnreleaseDateUnknown and UnpostedEventDateUnknown.

Rich text and XML are separate concerns

API v2 doesn't have an XML output mode. The standard response is JSON, and rich text is represented in Markdown. If an application needs the old formatting behavior, markupFormat=legacy can help with markup formatting - but it doesn't convert the v2 response into the old XML schema.

Plan for these as separate compatibility issues: output format, markup representation, and data structure. A formatting option won't fix code that expects legacy XPath-like locations or XML element names.

Use a migration checklist

1. Inventory every classic call. Record the endpoint, parameters, requested fields, output format, request frequency, and what consumes the response.
2. Map each call to v2. Replace expr with query.term, choose the equivalent query-area parameter where relevant, and define the required fields explicitly.
3. Implement cursor paging. Pick a starting pageSize, save and reuse each nextPageToken as pageToken, and stop only when there's no next token. Don't assume "bigger page" equals "fetch everything."
4. Update the parser. Read nested fields, accept arrays and missing values, normalize enums, and parse ISO 8601 dates without leaning on display strings.
5. Compare representative queries. Check total counts, record IDs, field values, and order. Include multi-page queries and studies with results.
6. Switch consumers in stages. Log errors and differences, keep a rollback path, and remove legacy assumptions only after v2 output is verified in production.

For high-impact data pipelines, compare a normalized internal representation rather than raw JSON/XML. For example, convert each response into a stable internal record with the NCT ID, title, status, phase, and relevant dates. That makes it easier to tell the difference between a true data difference and a harmless structural change.

When is the legacy endpoint reasonable?

Use a legacy endpoint when XML is a hard short-term requirement and rewriting the parser immediately would create more operational risk than a temporary compatibility layer. These endpoints are built to mimic classic behavior as closely as possible, which can make the transition smoother for older clients.

There are real trade-offs, though:

• Legacy endpoints return XML only. JSON isn't supported on those routes.
• When expr is used, retrieval is limited to the first 10,000 studies.
• The legacy study-fields endpoint omits FlowReasonNumUnits and OrgStudyIdDomain; NLM notes these fields contain no data in any study.
• Legacy responses report their own API version, separate from the v2 version endpoint.

If you adopt the shim, set an explicit removal condition. For example: keep it until the XML parser is replaced and v2 results pass your comparison tests. Without an exit criterion, a "temporary" bridge tends to become permanent, and the compatibility surface gets narrower over time.

Use bulk download for a full registry mirror

If you're trying to mirror the complete registry, don't page through search results. Use the bulk download endpoint. The v2 download route can provide a ZIP of JSON files, with each study file matching the single-study v2 schema.

Plan for file size, processing time, and schema evolution. The registry contained 606,964 studies in the live check reported on October 14, 2026, so this isn't a small download. Store it durably, validate the archive before processing, and make ingestion resumable. For targeted queries, the search endpoint is usually the better fit; for a complete local copy, bulk download is the simpler route.

Key takeaways

• The classic API was retired on June 25, 2024; old API paths aren't a fallback.
• /api/v2/studies replaces the classic study-search endpoints, but the response model is different.
• Translate rank-based paging into cursor-based paging, and set sorting explicitly when order matters.
• Treat legacy XML as a time-limited compatibility bridge, not the default path.
• Test the whole pipeline - from query construction to parsing and downstream display.