scientific-skills/database-lookup/references/cbioportal.md
https://www.cbioportal.org/api
No authentication for the public instance. Private/institutional instances (e.g. genie.cbioportal.org) require a data access token via Authorization: Bearer <token> header.
Accept: application/json
Content-Type: application/json
Most list endpoints support these:
| Parameter | Type | Description | Default |
|---|---|---|---|
projection | string | Detail level: ID, SUMMARY, DETAILED, META | SUMMARY |
pageNumber | int | Zero-based page index | 0 |
pageSize | int | Results per page | 10000000 |
sortBy | string | Property to sort by | varies |
direction | string | ASC or DESC | ASC |
| Method | Endpoint | Description |
|---|---|---|
| GET | /studies | List all cancer studies |
| GET | /studies/{studyId} | Get a single study |
| POST | /studies/fetch | Fetch multiple studies by ID |
Example:
GET https://www.cbioportal.org/api/studies?projection=SUMMARY&pageSize=10
GET https://www.cbioportal.org/api/studies/brca_tcga
Response fields: studyId, name, description, cancerTypeId, pmid, citation, allSampleCount, referenceGenome, publicStudy, importDate
| Method | Endpoint | Description |
|---|---|---|
| GET | /cancer-types | List all cancer types |
| GET | /cancer-types/{cancerTypeId} | Get one cancer type |
Response fields: cancerTypeId, name, shortName, dedicatedColor, parent
| Method | Endpoint | Description |
|---|---|---|
| GET | /genes | List all genes (paginated) |
| GET | /genes/{geneId} | Gene by Hugo symbol or Entrez ID |
| GET | /genes/{geneId}/aliases | Gene aliases |
| POST | /genes/fetch | Fetch multiple genes |
Example:
GET https://www.cbioportal.org/api/genes/TP53
Response: {"entrezGeneId": 7157, "hugoGeneSymbol": "TP53", "type": "protein-coding"}
| Method | Endpoint | Description |
|---|---|---|
| GET | /molecular-profiles | All profiles across all studies |
| GET | /studies/{studyId}/molecular-profiles | Profiles in a study |
| GET | /molecular-profiles/{molecularProfileId} | Single profile |
Profile types (molecularAlterationType): MUTATION_EXTENDED, COPY_NUMBER_ALTERATION, MRNA_EXPRESSION, PROTEIN_LEVEL, METHYLATION
Example:
GET https://www.cbioportal.org/api/studies/brca_tcga/molecular-profiles
| Method | Endpoint | Description |
|---|---|---|
| GET | /molecular-profiles/{profileId}/mutations | Mutations in a profile |
| POST | /molecular-profiles/{profileId}/mutations/fetch | Filtered mutation query |
| POST | /mutations/fetch | Multi-profile mutation fetch |
Parameters for GET:
| Parameter | Type | Description |
|---|---|---|
sampleListId | string | Sample list to query (e.g. brca_tcga_all) |
entrezGeneId | int | Filter by gene |
projection | string | SUMMARY, DETAILED, ID, META |
Example — TP53 mutations in TCGA breast cancer:
GET https://www.cbioportal.org/api/molecular-profiles/brca_tcga_mutations/mutations?sampleListId=brca_tcga_all&entrezGeneId=7157&projection=DETAILED
POST body for multi-gene fetch:
{
"sampleListId": "brca_tcga_all",
"entrezGeneIds": [7157, 672]
}
Response fields: entrezGeneId, sampleId, patientId, proteinChange, mutationType, mutationStatus, chr, startPosition, endPosition, referenceAllele, variantAllele, variantType, ncbiBuild, tumorAltCount, tumorRefCount
| Method | Endpoint | Description |
|---|---|---|
| GET | /molecular-profiles/{profileId}/discrete-copy-number | CNA data |
| POST | /molecular-profiles/{profileId}/discrete-copy-number/fetch | Filtered CNA query |
| POST | /discrete-copy-number/fetch | Multi-profile CNA fetch |
| Method | Endpoint | Description |
|---|---|---|
| GET | /molecular-profiles/{profileId}/molecular-data | Expression/methylation data |
| POST | /molecular-data/fetch | Multi-profile molecular data fetch |
| Method | Endpoint | Description |
|---|---|---|
| GET | /studies/{studyId}/clinical-data | Clinical data for a study |
| POST | /clinical-data/fetch | Multi-study clinical data |
| GET | /studies/{studyId}/clinical-attributes | Available clinical attributes |
Parameters for GET:
| Parameter | Type | Description |
|---|---|---|
clinicalDataType | string | PATIENT or SAMPLE |
attributeId | string | e.g. OS_STATUS, OS_MONTHS, CANCER_TYPE |
Example:
GET https://www.cbioportal.org/api/studies/brca_tcga/clinical-data?clinicalDataType=PATIENT&attributeId=OS_STATUS&projection=SUMMARY
| Method | Endpoint | Description |
|---|---|---|
| GET | /studies/{studyId}/patients | Patients in a study |
| GET | /studies/{studyId}/samples | Samples in a study |
| POST | /patients/fetch | Multi-study patient fetch |
| POST | /samples/fetch | Multi-study sample fetch |
| Method | Endpoint | Description |
|---|---|---|
| GET | /studies/{studyId}/sample-lists | Predefined sample groups |
| GET | /sample-lists/{sampleListId} | Single sample list |
| Method | Endpoint | Description |
|---|---|---|
| GET | /gene-panels | All gene panels |
| GET | /gene-panels/{genePanelId} | Panel details with gene list |
| POST | /gene-panel-data/fetch | Which panels cover which samples |
| Method | Endpoint | Description |
|---|---|---|
| POST | /treatments/patient | Patient-level treatment data |
| POST | /treatments/sample | Sample-level treatment data |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health | Server health check |
| GET | /info | Portal version, DB schema version |
GET /studies — browse available cancer studies, get studyId valuesGET /studies/{studyId}/molecular-profiles — find profile IDs (e.g. brca_tcga_mutations, brca_tcga_gistic)GET /studies/{studyId}/sample-lists — find sample list IDs (e.g. brca_tcga_all, brca_tcga_sequenced)No published rate limits. Be courteous — avoid hammering with many concurrent requests. For bulk data needs, cBioPortal offers downloadable datasets at https://docs.cbioportal.org/downloads/.
{cancer_type}_{source} (e.g. brca_tcga, luad_tcga, prad_mskcc_2017){studyId}_mutations, {studyId}_gistic, {studyId}_rna_seq_v2_mrnaprojection=DETAILED to get the richest response including nested objects/fetch endpoints are for batch queries across multiple studies, genes, or samples — they're the most flexible way to queryTP53) and Entrez IDs (7157)