# NCBI ClinVar Variant Scraper (`parseforge/clinvar-esummary-scraper`) Actor

Scrapes NCBI ClinVar variant summaries via the Esummary endpoint. Provide a gene or variant search term and get back flat records with variant ID, clinical significance, review status, and more.

- **URL**: https://apify.com/parseforge/clinvar-esummary-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** Automation, Integrations, Developer tools
- **Stats:** 2 total users, 1 monthly users, 89.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $7.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

### NCBI ClinVar Variant Scraper

**Scrape ClinVar variant summaries by gene, variant name, or clinical significance, up to a million records per run.** Each record returns the full Esummary payload: variant ID, gene, clinical significance, review status, and more. No API key required. Export to JSON, CSV, Excel, or XML.

NCBI ClinVar's E-utilities API requires you to build URLs, handle XML parsing, and paginate through results. This Actor reads the Esummary endpoint directly, accepts a gene or variant search term, and returns each matching variant record in a flat, consistent schema. You control the number of records and the search filter, and the Actor handles the rest.

| Who uses it | What they scrape NCBI ClinVar for |
|---|---|
| Clinical geneticists | Pull variant-level evidence for a gene panel before a case review. |
| Bioinformatics engineers | Feed a variant annotation pipeline with fresh ClinVar clinical significance data. |
| Rare disease researchers | Gather all ClinVar records for a candidate gene to cross-reference with phenotype databases. |
| Pharma variant scientists | Monitor ClinVar submissions for a target gene to track emerging pathogenicity assertions. |

### What it does

This Actor collects ClinVar variant summaries from the NCBI Esummary API by gene or variant search term and returns each record as a flat row.

- 🧬 **Gene or variant search:** pass a gene symbol like BRCA1, a variant like NM\_007294.4:c.5266dup, or a clinical significance filter like pathogenic\[clinsig].
- 📦 **Full Esummary payload:** every record includes variant ID, gene, clinical significance, review status, and all other fields returned by the Esummary endpoint.
- 🔢 **Configurable volume:** set a maximum from 1 to 1,000,000 records per run to match your use case.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with NCBI ClinVar data

**🧬 Build a gene-level evidence dump.**

A clinical geneticist runs the Actor with searchTerm=BRCA1 and maxItems=500 to collect all ClinVar records for the gene before a variant interpretation meeting.

**📊 Feed a variant annotation pipeline.**

A bioinformatics engineer runs the Actor nightly with a list of variant accessions to pull fresh clinical significance and review status into an internal annotation database.

**🔍 Cross-reference rare disease candidates.**

A rare disease researcher runs the Actor with a candidate gene symbol and compares the ClinVar clinical significance against OMIM and Orphanet phenotype data.

**📈 Monitor pathogenicity assertions over time.**

A pharma variant scientist runs the Actor weekly for a target gene to detect new pathogenic submissions or changes in review status.

### Why choose this scraper

| | What you get |
|---|---|
| **No API key** | The Actor calls the public NCBI E-utilities endpoint; you do not need to register an NCBI account or manage an API key. |
| **Flat output** | Every variant record is returned as a flat row, ready for pandas, Excel, or a database load. |
| **Flexible search** | Use any ClinVar search term that works on the website, including boolean filters like pathogenic\[clinsig] AND brca1\[gene]. |

### How it compares

This Actor focuses on the ClinVar Esummary endpoint for flat variant summaries. The other ClinVar scraper may target a different endpoint or schema, and the rare disease scraper covers a different NCBI database entirely.

| Feature | ParseForge | NCBI Clinvar Variants Scraper | Rare Disease Lookup - OMIM + Orphanet + MedGen API |
|---|---|---|---|
| ClinVar variant records | Yes, via Esummary endpoint | Yes | Not listed |
| Gene or variant search term | Yes | Not listed | Not listed |
| Clinical significance filter | Yes, via search term | Not listed | Not listed |
| No API key required | Yes | Not listed | Not listed |
| Rare disease definitions (OMIM, Orphanet) | Not listed | Not listed | Yes |

### Configure the run

Drive the Actor with a gene symbol, variant accession, or a clinical significance filter, and set a maximum record count to limit the run. The Input tab lists every parameter.

A first run with the defaults:

```json
{
 "maxItems": 10,
 "searchTerm": "BRCA1"
}
```

A larger pull:

```json
{
 "maxItems": 200,
 "searchTerm": "BRCA1"
}
```

### Pricing

Pay-per-result: **$0.0085 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $0.85 |
| 1,000 results | $8.50 |
| 10,000 results | $85.00 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [NCBI ClinVar Variant Scraper](https://apify.com/parseforge/clinvar-esummary-scraper?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to NCBI ClinVar through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=parseforge/clinvar-esummary-scraper"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting no results?**

Check your search term. Try the same term on the ClinVar website to confirm it returns records. If the term is valid, reduce maxItems to a small number and test again. Some very broad searches may time out; add a gene or clinical significance filter to narrow the query.

**The run timed out. What should I do?**

Increase the run timeout in the Actor's settings, or reduce maxItems. If you are searching a very large gene like TTN, add a clinical significance filter to reduce the result set.

**Some fields are empty in the output.**

ClinVar records vary in completeness. If a field like clinical significance is empty, the submitting lab may not have provided it. This is expected and reflects the source data.

**I get an NCBI rate-limit error.**

The public E-utilities endpoint allows about 3 requests per second without an API key. If you hit the limit, the Actor backs off automatically. For higher throughput, register an NCBI API key and pass it as an input parameter.

**The search term with special characters is not working.**

URL-encode characters like spaces, colons, and brackets in your search term. For example, use pathogenic%5Bclinsig%5D instead of pathogenic\[clinsig].

### FAQ

| Question | Answer |
|---|---|
| Do I need an NCBI API key? | No. This Actor uses the public E-utilities endpoint and does not require an NCBI account or API key. If you have a key and want higher rate limits, you can pass it as an input parameter. |
| What search terms can I use? | Any term that works in the ClinVar search box: gene symbols (BRCA1), variant accessions (NM\_007294.4:c.5266dup), or fielded queries like pathogenic\[clinsig] or brca1\[gene] AND pathogenic\[clinsig]. |
| How many records can I get in one run? | You set the maximum with the maxItems input, from 1 up to 1,000,000 records. The Actor stops when it reaches your limit or when ClinVar has no more matching records. |
| What fields are in the output? | The Actor returns the full Esummary payload for each variant. The exact fields depend on the ClinVar record, but typically include variant ID, gene, clinical significance, review status, and last evaluated date. |
| Can I filter by clinical significance? | Yes. Use a search term like pathogenic\[clinsig] or likely pathogenic\[clinsig] to return only variants with that clinical significance. |
| Does this Actor handle VCF coordinates? | The Esummary endpoint returns variant-level summaries, not VCF coordinates. For genomic coordinates, use the ClinVar VCF files or the full Efetch endpoint. |
| What export formats are supported? | You can export your dataset from Apify in JSON, CSV, Excel, XML, or RSS feed formats. |
| How does this differ from the NCBI Clinvar Variants Scraper? | This Actor targets the Esummary endpoint, which returns a flat summary for each variant. The other scraper may collect different fields or use a different endpoint. Check the sample output to see which schema fits your workflow. |
| Can I run this on a schedule? | Yes. Use Apify's scheduler to run the Actor daily, weekly, or on any cron schedule to keep your ClinVar data fresh. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by National Center for Biotechnology Information, U.S. National Library of Medicine. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

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

How many variant records to collect per run.

## `searchTerm` (type: `string`):

Search term for ClinVar (e.g. BRCA1, pathogenic\[clinsig]).

## Actor input object example

```json
{
  "maxItems": 10,
  "searchTerm": "BRCA1"
}
```

# Actor output Schema

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

No description

# 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 = {
    "maxItems": 10,
    "searchTerm": "BRCA1"
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/clinvar-esummary-scraper").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 = {
    "maxItems": 10,
    "searchTerm": "BRCA1",
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/clinvar-esummary-scraper").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 '{
  "maxItems": 10,
  "searchTerm": "BRCA1"
}' |
apify call parseforge/clinvar-esummary-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/clinvar-esummary-scraper"
        }
    }
}

```

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/EvWDEyzcIa1MHxOb3/builds/9C6HOOLcKGS5i5cRN/openapi.json