# Clinical Trial Matcher (`a.jonzy/clinical-trial-matcher`) Actor

Search ClinicalTrials.gov for parsed eligibility lists, age and sex limit checks and open sites. Registry data, not medical advice. Official API.

- **URL**: https://apify.com/a.jonzy/clinical-trial-matcher.md
- **Developed by:** [Aidan Jones](https://apify.com/a.jonzy) (community)
- **Categories:** Other, Agents, Automation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Clinical Trial Matcher

> **Read this first.** This actor returns registry data. It is not medical advice and it does not decide whether anyone is eligible for a trial. Registry records can be incomplete or out of date. Always confirm eligibility, status and sites with the trial team and a clinician. Do not enter identifying patient data (use a rough age and sex only).

Search ClinicalTrials.gov and get one clean dataset: inclusion and exclusion criteria split into lists, age and sex limits checked against your patient, and the recruiting sites in the place you choose. Built on the official ClinicalTrials.gov API v2. No scraping.

Use it to shortlist trials for a patient or a condition, build a trial finder, track new trials in a disease area, or feed structured eligibility into a screening workflow.

### What you get

- Search by condition, drug or device, free text, country, state and city
- Filters: recruitment status (open statuses by default), phase, study type, posted results
- Age and sex limit check: give an age and a sex and trials whose registered limits exclude them are dropped and not billed. Trials with no limit are kept. This compares two registry fields only; it is not an eligibility determination
- Eligibility parsed into `inclusionCriteria` and `exclusionCriteria` lists, with the original text available on request
- `openLocations`: only the recruiting or not-yet-recruiting sites in the country, state and city you asked for
- Optional central contacts (name, phone, email) as registered by the sponsor

### Price

Pay per event. You pay for trials returned.

| Event | Price |
|---|---|
| Actor start | $0.005 per start event. Apify bills one start event per GB of memory, minimum one; the default run uses 512 MB, so one event. |
| Clinical trial returned | $0.008 |

100 trials cost about $0.81. Trials dropped by the patient filters and error items are not charged. Set `maxItems` to cap spend.

### Example input

```json
{
    "condition": "melanoma",
    "country": "United States",
    "state": "Texas",
    "phases": ["PHASE2", "PHASE3"],
    "patientAge": 45,
    "patientSex": "MALE",
    "onlyWithOpenSite": true,
    "maxItems": 20
}
```

### Example output

```json
{
    "status": "found",
    "nctId": "NCT04370587",
    "title": "A Clinical Study of Intratumoral MVR-T3011 (T3011) Given as a Single Agent and in Combination With Intravenous Pembrolizumab in Participants With Advanced or Metastatic Solid Tumors",
    "overallStatus": "RECRUITING",
    "studyType": "INTERVENTIONAL",
    "phases": ["PHASE1", "PHASE2"],
    "conditions": ["Solid Tumor", "Melanoma", "HNSCC", "Sarcoma"],
    "interventions": [{ "type": "BIOLOGICAL", "name": "T3011" }, { "type": "COMBINATION_PRODUCT", "name": "T3011 + pembrolizumab" }],
    "sponsor": "ImmVira Pharma Co. Ltd",
    "enrollment": 30,
    "minimumAge": "18 Years",
    "maximumAge": null,
    "sex": "ALL",
    "healthyVolunteers": false,
    "inclusionCriteria": ["Age 18 years or older.", "..."],
    "exclusionCriteria": ["Have only uninjectable tumors..", "..."],
    "meetsRegisteredAgeSexLimits": true,
    "mismatchReasons": [],
    "openLocations": [{ "facility": "Mary Crowley Cancer Research", "city": "Dallas", "state": "Texas", "country": "United States", "zip": "75230", "status": "RECRUITING" }],
    "hasResults": false,
    "url": "https://clinicaltrials.gov/study/NCT04370587"
}
```

A run summary (trials returned, scanned, skipped, total matches) is saved under the key-value store key `SUMMARY`.

### FAQ

**Where does the data come from?** The ClinicalTrials.gov API v2, a free public API of the U.S. National Library of Medicine. Records are as registered by trial sponsors.

**Is `meetsRegisteredAgeSexLimits` an eligibility decision?** No. It is `null` unless you set a patient age, sex or healthy-volunteer filter, and then it only compares the registered age, sex and healthy-volunteer fields. The inclusion and exclusion lists are the sponsor's own text, split into items. Eligibility is decided by the trial team.

**Why do some criteria look cut mid-sentence?** The lists follow the line breaks in the registered text. Turn on `includeEligibilityText` to see the original.

**Are contacts personal data?** Central contacts are the enquiry channel the sponsor published for recruitment. They are off by default. Use them only to enquire about a trial, and follow the anti-spam, privacy and marketing laws that apply to you; do not add them to mailing lists or resell them.

**Can I search several conditions?** Run once per condition, or put several terms in `searchTerms`.

### Data and limits

- Source: ClinicalTrials.gov (NLM). Trial status and sites change often; results reflect the registry at run time.
- Up to 2000 trials per run.
- If a location filter returns nothing, the run summary carries a `warning`. US state codes (TX) and US/USA/UK are expanded; other abbreviations are not.
- Age limits are compared in years. Months, weeks and days are converted. Missing limits never exclude a trial.
- This is a research aid. It is not medical advice.

# Actor input Schema

## `condition` (type: `string`):

For example melanoma, type 2 diabetes or Alzheimer's disease. At least one of condition, intervention or search terms is required.

## `intervention` (type: `string`):

For example pembrolizumab. Optional.

## `searchTerms` (type: `string`):

Free text searched across the whole trial record. Optional.

## `country` (type: `string`):

Only trials with a site in this country, and only that country's sites in the output. Example: United States. US, USA and UK are expanded.

## `state` (type: `string`):

Optional. Example: Texas. Two-letter US codes such as TX are expanded.

## `city` (type: `string`):

Optional. Example: Houston.

## `statuses` (type: `array`):

Trial statuses to include. Defaults to the three open statuses: RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION. Other values: ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, UNKNOWN.

## `phases` (type: `array`):

Optional. Any of EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA.

## `studyType` (type: `string`):

Interventional trials test a treatment; observational studies do not.

## `hasResultsOnly` (type: `boolean`):

Keep only trials that have posted results on ClinicalTrials.gov. Combine with a COMPLETED status.

## `patientAge` (type: `number`):

When set, trials whose registered age limits exclude this age are dropped and not billed. Trials with no limit are kept. Use a rough age; do not enter identifying patient data.

## `patientSex` (type: `string`):

When set to male or female, trials limited to the other sex are dropped and not billed. This is the registered participant sex, not gender identity.

## `healthyVolunteer` (type: `boolean`):

Drops trials that do not accept healthy volunteers. Only applied when patient age or sex is also set.

## `onlyWithOpenSite` (type: `boolean`):

Drop trials with no recruiting or not-yet-recruiting site matching country, state and city.

## `includeEligibilityText` (type: `boolean`):

Adds the registered eligibility criteria text next to the parsed lists.

## `includeContacts` (type: `boolean`):

Adds the central contact name, phone and email the sponsor registered for enquiries.

## `maxItems` (type: `integer`):

Safety cap on trials returned and billed in one run.

## Actor input object example

```json
{
  "condition": "melanoma",
  "country": "United States",
  "statuses": [
    "RECRUITING",
    "NOT_YET_RECRUITING"
  ],
  "studyType": "any",
  "hasResultsOnly": false,
  "patientSex": "ALL",
  "healthyVolunteer": false,
  "onlyWithOpenSite": false,
  "includeEligibilityText": false,
  "includeContacts": false,
  "maxItems": 100
}
```

# Actor output Schema

## `results` (type: `string`):

One item per clinical trial returned. A failed search produces one item with status error.

## `summary` (type: `string`):

Counts of trials returned, scanned and skipped, plus the total matches on ClinicalTrials.gov.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "condition": "melanoma",
    "country": "United States",
    "statuses": [
        "RECRUITING",
        "NOT_YET_RECRUITING"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("a.jonzy/clinical-trial-matcher").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "condition": "melanoma",
    "country": "United States",
    "statuses": [
        "RECRUITING",
        "NOT_YET_RECRUITING",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("a.jonzy/clinical-trial-matcher").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "condition": "melanoma",
  "country": "United States",
  "statuses": [
    "RECRUITING",
    "NOT_YET_RECRUITING"
  ]
}' |
apify call a.jonzy/clinical-trial-matcher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,a.jonzy/clinical-trial-matcher"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OnYfkxS8fMgjMeW9x/builds/fN3Hgvn2lqL1JeMNv/openapi.json