# cBioPortal Cancer Genomics Extractor (`datamule/cbioportal-cancer-genomics-extractor`) Actor

Point at ANY cBioPortal instance (the MSKCC flagship, BCGSC, GENIE, institutional mirrors) and pull cancer-genomics metadata: studies, the OncoTree cancer-type taxonomy, molecular profiles, and genes. One actor, the whole cBioPortal REST API, every row lossless.

- **URL**: https://apify.com/datamule/cbioportal-cancer-genomics-extractor.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 genomics records

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/platform/actors/running/actors-in-store#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

## cBioPortal Cancer Genomics Extractor

Point at **any cBioPortal instance** and pull structured cancer-genomics metadata — **studies, the OncoTree cancer-type taxonomy, molecular profiles, and genes** — as clean, tabular JSON. One actor speaks to every cBioPortal deployment, because they all expose the identical Swagger-generated REST API.

cBioPortal is the open-source standard for exploring multidimensional cancer-genomics data. The public **MSKCC flagship** (`www.cbioportal.org`) hosts 500+ published studies; the **BC Genome Sciences Centre** mirror (`cbioportal.bcgsc.ca`), GENIE, and dozens of institutional deployments run the same API. This actor turns any of them into a dataset — no per-portal scraper, no HTML parsing, no host guessing.

### What you can extract

Pick a **mode**:

| Mode | Endpoint | One row per… |
|------|----------|--------------|
| `studies` *(default)* | `/api/studies` | cancer study (id, cancer type, sample count, reference genome, PMID, import date) |
| `cancerTypes` | `/api/cancer-types` | OncoTree cancer-type node (name, short name, parent, color) |
| `study-detail` | `/api/studies/{id}` | the full DETAILED record for one study — every per-datatype sample count |
| `molecular-profiles` | `/api/molecular-profiles` | molecular profile — portal-wide, or for one study |
| `genes` | `/api/genes` | gene in the portal's gene table (Entrez ID + HUGO symbol) |

Every row carries the mapped, human-friendly fields **plus a lossless `_raw`** object with the complete original API record, so nothing is ever dropped.

### Example input

```json
{
  "servers": ["https://www.cbioportal.org", "https://cbioportal.bcgsc.ca"],
  "mode": "studies",
  "pageSize": 500,
  "maxRecords": 1000
}
```

Full-study detail for one study:

```json
{
  "server": "https://www.cbioportal.org",
  "mode": "study-detail",
  "studyId": "brca_tcga_pan_can_atlas_2018"
}
```

### Input reference

- **`server`** / **`servers`** — one cBioPortal base URL, or a list to query several instances at once. Accepts a bare host, an `https://` URL, a proxied path prefix, or a URL ending in `/api` (all normalised). At least one is required.
- **`mode`** — what to extract (see the table above). Default `studies`.
- **`studyId`** — required for `study-detail`; optional filter for `molecular-profiles`.
- **`pageSize`** — records requested per API page (default 500).
- **`maxRecords`** — global cap on rows emitted across all servers (each row is one billable event). Leave empty to emit everything.
- **`userAgent`**, **`timeoutSecs`**, **`bearer`**, **`extraHeaders`** — optional request tuning and auth for gated deployments.

### Behaviour & robustness

- **Instance-agnostic pagination.** cBioPortal honours `pageSize` everywhere but its `pageNumber` handling varies by endpoint (the studies list ignores it; genes/cancer-types honour it). The actor paginates defensively — de-duplicates by natural key, stops on a short page, and escalates to a single large pull when a server ignores `pageNumber` — so the whole collection is captured on any instance.
- **Auth-gated instances are skipped, not fatal.** GENIE / triage / pediatric deployments return 401/403; those servers are skipped with a warning and the batch continues. If **every** server is skipped, the run fails fast rather than emitting an empty dataset silently.
- **A reachable server with zero public studies is a real zero** — never fabricated data.

### Pricing

Pay-per-event: **one event per record** (row) emitted. Set `maxRecords` to bound the cost of a run.

### Notes

This actor reads **public metadata** from cBioPortal's documented REST API. It does not download raw genomic/sample-level patient data. Respect each instance's terms of use.

# Actor input Schema

## `server` (type: `string`):

The base URL of ANY cBioPortal instance. ONE actor speaks to all of them — the MSKCC public flagship (https://www.cbioportal.org), the BC Genome Sciences Centre mirror (https://cbioportal.bcgsc.ca), GENIE, and dozens of institutional deployments, because every install exposes the identical Swagger-generated REST API. You can pass the bare host, an https URL, a proxied path prefix, or a URL ending in /api — the actor normalises it. Required unless you use "Servers" below.

## `servers` (type: `array`):

Optional: run the SAME mode across multiple cBioPortal instances at once (the flagship plus institutional mirrors, say). Each output row is tagged with its \_server. Use this OR the single "cBioPortal base URL" above (at least one is required). A server that is unreachable, auth-gated (401/403), or returns a non-JSON body is skipped with a warning and the batch continues; if EVERY server is skipped the run fails fast.

## `mode` (type: `string`):

Which cBioPortal collection to pull. 'studies' = one row per cancer study (the default). 'cancerTypes' = the portal's cancer-type / OncoTree taxonomy. 'study-detail' = the DETAILED record (all per-datatype sample counts) for the one study named in 'Study ID'. 'molecular-profiles' = molecular profiles, either portal-wide or (if 'Study ID' is set) for one study. 'genes' = the portal's gene table (Entrez ID + HUGO symbol).

## `studyId` (type: `string`):

A cBioPortal study identifier, e.g. 'acbc\_mskcc\_2015' or 'brca\_tcga\_pan\_can\_atlas\_2018'. REQUIRED for mode 'study-detail'. OPTIONAL for mode 'molecular-profiles' — when set, only that study's profiles are returned; when empty, the portal-wide profile list is returned. Ignored for the other modes.

## `pageSize` (type: `integer`):

How many records to request per API page (default 500). cBioPortal honours pageSize everywhere; the actor paginates defensively and de-duplicates, so this mainly tunes request size. Larger pages = fewer round-trips.

## `maxRecords` (type: `integer`):

A GLOBAL cap on the number of rows emitted across ALL servers (each row is one billable event). Reached mid-collection, the run stops deterministically. Leave empty to emit the entire collection from every reachable server. Useful to keep a first test run cheap.

## `userAgent` (type: `string`):

Optional override for the request User-Agent. A descriptive User-Agent is sent by default — some data centres throttle or reject a blank / generic UA. Only override if a specific instance asks you to identify differently.

## `timeoutSecs` (type: `integer`):

How long to wait for the server to answer each request (default 120). Large gene / study lists can be slow; servers also enforce their own timeouts.

## `bearer` (type: `string`):

Optional bearer token for an auth-gated cBioPortal deployment (sent as Authorization: Bearer \*\*\*). NOT required for the public flagship or BCGSC. Never logged.

## `extraHeaders` (type: `object`):

Optional extra HTTP headers as a JSON object, e.g. {"X-Api-Key": "..."} for a gateway-fronted instance. Not required for public servers. Header values are never logged.

## Actor input object example

```json
{
  "server": "https://www.cbioportal.org",
  "servers": [
    "https://www.cbioportal.org",
    "https://cbioportal.bcgsc.ca"
  ],
  "mode": "studies",
  "pageSize": 500,
  "maxRecords": 1000
}
```

# 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 = {
    "server": "https://www.cbioportal.org",
    "servers": [
        "https://www.cbioportal.org",
        "https://cbioportal.bcgsc.ca"
    ],
    "pageSize": 500,
    "maxRecords": 1000
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/cbioportal-cancer-genomics-extractor").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 = {
    "server": "https://www.cbioportal.org",
    "servers": [
        "https://www.cbioportal.org",
        "https://cbioportal.bcgsc.ca",
    ],
    "pageSize": 500,
    "maxRecords": 1000,
}

# Run the Actor and wait for it to finish
run = client.actor("datamule/cbioportal-cancer-genomics-extractor").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "server": "https://www.cbioportal.org",
  "servers": [
    "https://www.cbioportal.org",
    "https://cbioportal.bcgsc.ca"
  ],
  "pageSize": 500,
  "maxRecords": 1000
}' |
apify call datamule/cbioportal-cancer-genomics-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/cbioportal-cancer-genomics-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/Z7FVCgUX6Pv5NUyoK/builds/NZrMpDu1g5P2hcd2q/openapi.json