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:

Key Endpoints

Studies

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

Response fields: cancerTypeId, name, shortName, dedicatedColor, parent

Genes

Example:

GET https://www.cbioportal.org/api/genes/TP53

Response: {"entrezGeneId": 7157, "hugoGeneSymbol": "TP53", "type": "protein-coding"}

Molecular Profiles

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

Parameters for GET:

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 /molecular-profiles/{profileId}/mutations/fetch (multi-gene, single profile; /mutations/fetch uses a different multi-study schema):

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

Molecular Data (expression, methylation)

Clinical Data

Parameters for GET:

Example:

GET https://www.cbioportal.org/api/studies/brca_tcga/clinical-data?clinicalDataType=PATIENT&attributeId=OS_STATUS&projection=SUMMARY

Patients & Samples

Sample Lists

Gene Panels

API surface and versions

Use the public OpenAPI schema at https://www.cbioportal.org/api/v3/api-docs/public for the selected instance. The current public schema does not expose /treatments/patient, /treatments/sample, or a global /discrete-copy-number/fetch; do not infer these routes from internal UI requests or older installations.

System

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

• Study IDs follow a pattern: {cancer_type}_{source} (e.g. brca_tcga, luad_tcga, prad_mskcc_2017)
• Molecular profile IDs extend the study ID: {studyId}_mutations, {studyId}_gistic, {studyId}_rna_seq_v2_mrna
• Use projection=DETAILED to get the richest response including nested objects
• POST /fetch endpoints are for batch queries across multiple studies, genes, or samples — they're the most flexible way to query
• Gene lookup accepts both Hugo symbols (TP53) and Entrez IDs (7157)
• The Swagger UI at https://www.cbioportal.org/api/swagger-ui/index.html documents every endpoint interactively