← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / database-lookup / references / cbioportal.md

cBioPortal API

Base URL

https://www.cbioportal.org/api

Auth

No authentication for the public instance. Private/institutional instances (e.g. genie.cbioportal.org) require a data access token via Authorization: Bearer <token> header.

Common Headers

Accept: application/json
Content-Type: application/json

Common Query Parameters

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

Key Endpoints

Studies

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

Cancer Types

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

Genes

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"}

Molecular Profiles

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

Mutations

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

Copy Number Alterations

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

Molecular Data (expression, methylation)

Method Endpoint Description
GET /molecular-profiles/{profileId}/molecular-data Expression/methylation data
POST /molecular-data/fetch Multi-profile molecular data fetch

Clinical Data

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

Patients & Samples

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

Sample Lists

Method Endpoint Description
GET /studies/{studyId}/sample-lists Predefined sample groups
GET /sample-lists/{sampleListId} Single sample list

Gene Panels

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

Treatments

Method Endpoint Description
POST /treatments/patient Patient-level treatment data
POST /treatments/sample Sample-level treatment data

System

Method Endpoint Description
GET /health Server health check
GET /info Portal version, DB schema version

Typical Workflow

  1. Find studies: GET /studies — browse available cancer studies, get studyId values
  2. Get molecular profiles: GET /studies/{studyId}/molecular-profiles — find profile IDs (e.g. brca_tcga_mutations, brca_tcga_gistic)
  3. Get sample lists: GET /studies/{studyId}/sample-lists — find sample list IDs (e.g. brca_tcga_all, brca_tcga_sequenced)
  4. Query data: Use the profile ID and sample list ID to fetch mutations, CNA, expression, or clinical data

Rate Limits

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/.

Tips