# Clinical Trial Lookup (`clinicaltrials.study`)

One ClinicalTrials.gov study by NCT number: status, phases, sponsor, conditions, interventions, key dates, enrollment, eligibility, primary outcomes and locations.

Docs: https://primaryapi.com/docs/api-reference/clinicaltrials/study

- Endpoint: `POST https://api.primaryapi.com/v1/run/clinicaltrials.study`
- Category: Knowledge & Data · Platform: `clinicaltrials` · Kind: lookup · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=clinicaltrials.study`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `nctId` | string | yes |  | pattern: ^NCT\d{8}$ | ClinicalTrials.gov identifier, e.g. "NCT04368728". |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `nctId` | string | ClinicalTrials.gov identifier, e.g. "NCT04368728" |
| `title` | string \| null | Brief title |
| `officialTitle` | string \| null |  |
| `acronym` | string \| null |  |
| `status` | string \| null | Overall recruitment status, e.g. RECRUITING, COMPLETED, TERMINATED |
| `whyStopped` | string \| null | Reason given when a study stopped early |
| `phases` | string[] | e.g. ["PHASE2","PHASE3"]; empty for observational studies |
| `studyType` | string \| null | INTERVENTIONAL, OBSERVATIONAL or EXPANDED_ACCESS |
| `leadSponsor` | string \| null |  |
| `leadSponsorClass` | string \| null | INDUSTRY, NIH, FED, OTHER_GOV, NETWORK, OTHER … |
| `collaborators` | string[] |  |
| `conditions` | string[] |  |
| `interventions` | object[] |  |
| `interventions[].type` | string \| null |  |
| `interventions[].name` | string \| null |  |
| `enrollment` | integer \| null |  |
| `enrollmentType` | string \| null | ACTUAL or ESTIMATED |
| `startDate` | string \| null | YYYY-MM-DD or YYYY-MM as registered |
| `primaryCompletionDate` | string \| null |  |
| `completionDate` | string \| null |  |
| `firstPostedDate` | string \| null | Date the record was first posted |
| `lastUpdatePostedDate` | string \| null | Date the latest update was posted (the record version) |
| `resultsFirstPostedDate` | string \| null |  |
| `hasResults` | boolean \| null |  |
| `countries` | string[] | Countries with a study location, sorted |
| `locationCount` | integer | Number of study locations |
| `url` | string | Study page on clinicaltrials.gov |
| `briefSummary` | string \| null |  |
| `orgStudyId` | string \| null | Sponsor's own study id |
| `statusVerifiedDate` | string \| null | Month the sponsor last verified the status, YYYY-MM |
| `lastKnownStatus` | string \| null | Status before the record went UNKNOWN |
| `eligibility` | object |  |
| `eligibility.sex` | string \| null |  |
| `eligibility.minimumAge` | string \| null |  |
| `eligibility.maximumAge` | string \| null |  |
| `primaryOutcomes` | string[] | Primary outcome measures (first 25) |
| `locations` | object[] | Study locations (first 200; locationCount has the total) |
| `locations[].facility` | string \| null |  |
| `locations[].city` | string \| null |  |
| `locations[].state` | string \| null |  |
| `locations[].country` | string \| null |  |
| `locations[].status` | string \| null |  |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/clinicaltrials.study" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nctId":"NCT04368728"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "nctId": "NCT04368728",
      "title": "string",
      "officialTitle": "string",
      "acronym": "string",
      "status": "string",
      "whyStopped": "string",
      "phases": [
        "string"
      ],
      "studyType": "string",
      "leadSponsor": "string",
      "leadSponsorClass": "string",
      "collaborators": [
        "string"
      ],
      "conditions": [
        "string"
      ],
      "interventions": [
        {
          "type": "string",
          "name": "string"
        }
      ],
      "enrollment": 0,
      "enrollmentType": "string",
      "startDate": "string",
      "primaryCompletionDate": "string",
      "completionDate": "string",
      "firstPostedDate": "string",
      "lastUpdatePostedDate": "string",
      "resultsFirstPostedDate": "string",
      "hasResults": true,
      "countries": [
        "string"
      ],
      "locationCount": 0,
      "url": "https://example.com",
      "briefSummary": "string",
      "orgStudyId": "string",
      "statusVerifiedDate": "string",
      "lastKnownStatus": "string",
      "eligibility": {
        "sex": "string",
        "minimumAge": "string",
        "maximumAge": "string"
      },
      "primaryOutcomes": [
        "string"
      ],
      "locations": [
        {
          "facility": "string",
          "city": "string",
          "state": "string",
          "country": "string",
          "status": "string"
        }
      ]
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=clinicaltrials.study`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Any update the sponsor posts changes lastUpdatePostedDate (and usually other fields), so a monitor on this API reports status changes, new results, new dates and new sites. An NCT number that is now an alias answers not found with reason "moved" and a hint naming the current record. Unknown NCT numbers are free.

## Legal

Source: ClinicalTrials.gov, U.S. National Library of Medicine (https://clinicaltrials.gov), as processed by ClinicalTrials.gov on the dates shown in each record (lastUpdatePostedDate); PrimaryAPI reshapes the record (field selection and renaming) and does not change its content. No endorsement by NLM is implied. Not medical advice.

