GDC API User's Guide
NCI Genomic Data Commons (GDC)
NCI GDC
© 2015-2024
Table of contents
51. API
51.1 Getting Started
51.1.1 The GDC Application Programming Interface (API): An Overview
51.1.2 Tools for communicating with the GDC API
61.1.3 API Endpoints
61.1.4 Entity UUIDs
71.1.5 Sample Request
71.1.6 Authentication
91.2 Search and Retrieval
91.2.1 Introducing Search and Retrieval Requests
101.2.2 Endpoints
281.2.3 Request Parameters
521.2.4 Alternative Request Format
521.2.5 Using Wildcards
521.2.6 Quicksearch Endpoint
531.2.7 Additional Examples
541.3 Downloading Files
541.3.1 Data endpoint
561.3.2 Manifest endpoint
581.4 Data Analysis
591.4.1 Endpoints
621.4.2 Genes Endpoint Examples
631.4.3 Gene Expression Examples
661.4.4 Simple Somatic Mutation Endpoint Examples
681.4.5 Simple Somatic Mutation Occurrence Endpoint Examples
701.4.6 Copy Number Variation Endpoint Examples
711.4.7 Copy Number Variation Occurrence Enpoint Examples
741.4.8 Analysis Endpoints
1041.5 BAM Slicing
1041.5.1 About the slicing endpoint
1051.5.2 Examples: Specifying a region
1051.5.3 Examples: Specifying a gene
1051.5.4 Examples: Specifying unmapped reads
1061.5.5 Errors
1081.6 Submission
1081.6.1 Overview
Table of contents
- 2/232 -
© 2015-2024
1081.6.2 Submission endpoint
1081.6.3 Submission Formats
1091.6.4 GDC Data Model
1101.6.5 Making Requests to the Submission API
1101.6.6 Submission Transactions
1131.6.7 Creating and Updating Entities
1241.6.8 Retrieving Entities
1281.6.9 Patching Entitites
1291.6.10 Deleting Entities
1301.6.11 Working With Files
1341.6.12 Querying Submitted Data Using GraphQL
1411.7 Using Python to Query the GDC API
1411.7.1 Querying Metadata
1421.7.2 Downloading Files
1461.7.3 Basic Troubleshooting
1471.8 Introduction to GDC GraphQL
1471.8.1 Using GDC GraphQL vs GDC REST API
1471.8.2 GDC GraphQL Overview
1471.8.3 GDC GraphQL Endpoints
1471.8.4 GDC GraphQL Schema
1481.8.5 Basic GraphQL queries in GDC
1491.8.6 Anatomy of a typical GDC GraphQL Query
1491.8.7 GDC GraphQL Examples
1511.9 System Information
1511.9.1 Overview
1511.9.2 GDC Notifications Endpoint
1511.9.3 API Status Endpoint
1531.10 Additional Examples
1531.10.1 Data Search and Retrieval
1611.11 Appendix A: Available Fields
1611.11.1 Field Listing by Endpoint
2031.11.2 Field Group Listing by Endpoint
2101.12 Appendix B: Key Terms
2111.13 Appendix C: Format of Submission Requests and Responses
2121.13.1 Status Messages
2131.14 API Release Notes
2151.14.1 v7.4.2
2151.14.2 v7.3.0
Table of contents
- 3/232 -
© 2015-2024
2151.14.3 v4.0.0
2161.14.4 v3.28.0
2161.14.5 v3.5.0
2171.14.6 v3.3.0
2171.14.7 v3.0.0
2171.14.8 v2.1.2
2181.14.9 v2.1.0
2181.14.10 v2.0.0
2191.14.11 v1.23.0
2191.14.12 v1.22.0
2201.14.13 v1.21.0
2211.14.14 v1.20.0
2221.14.15 v1.19.0
2221.14.16 v1.18.0
2221.14.17 v1.17.0
2231.14.18 v1.16.0
2231.14.19 v1.15.0
2241.14.20 v1.14.1
2241.14.21 v1.14.0
2251.14.22 v1.13.0
2251.14.23 v1.12.0
2261.14.24 v1.11.0
2261.14.25 v1.10.0
2271.14.26 v1.9.0
2271.14.27 v1.8.0
2271.14.28 v1.7.1
2281.14.29 v1.5.0
2291.14.30 v1.4.0
2291.14.31 v1.3.1
2301.14.32 v1.2.0
2311.14.33 v1.1.0
2311.14.34 v1.0.1
Table of contents
- 4/232 -
© 2015-2024
1. API
1.1 Getting Started
1.1.1 The GDC Application Programming Interface (API): An Overview
The GDC API drives the GDC Data and Submission Portals and provides programmatic access to GDC functionality. This includes
searching for, downloading, and submitting data and metadata. The GDC API uses JSON as its communication format, and
standard HTTP methods like GET , PUT , POST and DELETE .
This guide explains how to construct and execute API requests and interpret API responses.
1.1.2 Tools for communicating with the GDC API
Many third-party tools can be used for communicating with the GDC API and for preparing and visualizing API calls.
Examples of tools for communicating with the GDC API:
Examples of tools that can help build GDC API calls:
NOTE: When using the command line tool curl be sure to use the bash shell only for compatibility reasons. All examples using curl
are using the bash shell.
The authentication token should be kept in a secure location, as it allows access to all data accessible by the associated user
account.
Tool Type
Curl Command line tool
HTTPie Command line tool
Postman REST Client App for Google Chrome and OS X
DHC REST Client Google Chrome extension
Google Chrome Google Chrome web browser
Tool Description
JSONLint Validate JSON
JSON Formatter Format, validate, and convert JSON to other formats
Percent-(URL)-encoding tool Tool for percent-encoding strings
1. API
- 5/232 -
© 2015-2024
1.1.3 API Endpoints
Communicating with the GDC API involves making calls to API endpoints. Each GDC API endpoint represents specific API
functionality, as summarized in the following table:
The HTTP URL that corresponds to the latest version of a GDC API endpoint is
https://api.gdc.cancer.gov/<endpoint> , where
<endpoint> is the name of the endpoint.
The HTTP URL of an endpoint corresponding to a specific major version of the GDC API is https://api.gdc.cancer.gov/<version>/
<endpoint> , where <endpoint> is the name of the endpoint and <version> is the GDC API version.
For example, the address of the latest version of the status endpoint is https://api.gdc.cancer.gov/status , whereas the address of
the status endpoint corresponding to version 0 of GDC API is https://api.gdc.cancer.gov/v0/status .
1.1.4 Entity UUIDs
All objects (
entities
) in the GDC are assigned a unique identifier in the form of a version 4 universally unique identifier (UUID). The
UUID uniquely identifies the entity in the GDC, and is stored in the entity's id property.
UUIDs are frequently used in GDC API requests and responses to identify specific entities like files, cases, and samples.
See GDC Data Model for details.
Endpoint Type Description
status Status Get the API status and version information
projects Search &
Retrieval
Search all data generated by a project
cases Search &
Retrieval
Find all files related to a specific case, or sample donor.
files Search &
Retrieval
Find all files with specific characteristics such as file_name, md5sum,
data_format and others.
annotations Search &
Retrieval
Search annotations added to data after curation
data Download Used to download GDC data
manifest Download Generates manifests for use with GDC Data Transfer Tool
slicing BAM Slicing Allows remote slicing of BAM format objects
submission Submission Returns the available resources at the top level above programs i.e., registered
programs
1.1.3 API Endpoints
- 6/232 -
© 2015-2024
1.1.5 Sample Request
The following is an example of a request to the files endpoint, which retrieves information about a MAF file stored in the GDC.
Download Script
1.1.6 Authentication
Authentication is required for downloading controlled-access data, and for all data submission functionality. The GDC API uses
tokens for authentication.
Users can obtain authentication tokens from the GDC Data Portal and the GDC Data Submission Portal. See the GDC Data
Submission Portal User's Guide for instructions.
Using Authentication Tokens
All API requests that require authentication must include a token as an X-Auth-Token custom HTTP header.
Shell Python
curl
https://api.gdc.cancer.gov/files/cb92f61d-041c-4424-a3e9-891b7545f351?pretty
=
true
import
requests
import
json
file_endpt
=
file_uuid
=
'cb92f61d-041c-4424-a3e9-891b7545f351'
response
=
requests
.
get
(
file_endpt
+
file_uuid
)
# OUTPUT METHOD 1: Write to a file.
file
=
open
(
"sample_request.json"
,
"w"
)
file
.
write
(
response
.
text
)
file
.
close
()
# OUTPUT METHOD 2: View on screen.
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
1.1.5 Sample Request
- 7/232 -
© 2015-2024
In the following example, an authentication token is saved as an environment variable and passed to curl to download a
controlled-access file:
Download Python Script
For more information about authentication tokens, including token expiration and rotation, see Data Security.
NOTE: The authentication token should be kept in a secure location, as it allows access to all data accessible by the associated
user account.
Shell Output Python
token
=
$(
cat
<gdc-token-text-file.txt>
)
curl
-O
-J
-H
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/data/fd89bfa5-b3a7-4079-bf90-709580c006e5'
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 4161M 100 4161M 0 0 281k 0 4:12:45 4:12:45 --:--:-- 1894k
import
requests
import
json
import
re
'''
This script will not work until $TOKEN_FILE_PATH
is replaced with an actual path.
'''
with
open
(
"$TOKEN_FILE_PATH"
,
"r"
)
as
token
:
token_string
=
str
(
token
.
read
()
.
strip
())
headers
=
{
'X-Auth-Token'
:
token_string
}
data_endpt
=
'https://api.gdc.cancer.gov/data/'
data_uuid
=
'fd89bfa5-b3a7-4079-bf90-709580c006e5'
headers
=
{
'X-Auth-Token'
:
token_string
}
response
=
requests
.
get
(
data_endpt
+
data_uuid
,
headers
=
headers
)
# The file name can be found in the header within the Content-Disposition key.
response_head_cd
=
response
.
headers
[
"Content-Disposition"
]
file_name
=
re
.
findall
(
"filename=(.+)"
,
response_head_cd
)[
0
]
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
1.1.6 Authentication
- 8/232 -
© 2015-2024
1.2 Search and Retrieval
1.2.1 Introducing Search and Retrieval Requests
The GDC API provides endpoints that search and retrieve information stored in the GDC according to the GDC Data Model. The
general format of requests to search & retrieval endpoints is described below.
Note: Queries described in this section work for datasets that have been released to the GDC Data Portal. Unreleased data that is
in the process of being submitted to GDC cannot be queried using these methods. See Submission to learn how to query
unreleased data using GraphQL.
Components of a Request
A typical search and retrieval API request specifies the following parameters:
• a filters parameter, that specifies the search terms for the query
• several parameters that specify the API response, such as:
• format — specifies response format (JSON, TSV, XML)
• fields — specifies the which data elements should be returned in the response, if available
• size — specifies the the maximum number of results to include in the response
• other parameters are described below.
Requests can be executed using HTTP GET or HTTP POST. GET requests are limited by maximum URL length, so the POST
method is recommended for large queries.
POST Example
The following is an example of an HTTP POST request to the files endpoint of the GDC API. It looks for Gene Expression
Quantification files associated with specific TCGA cases (represented by TCGA barcodes) and retrieves the associated biospecimen
metadata in TSV format.
REQUEST
PAYLOAD
curl --request POST --header "Content-Type: application/json" --data @Payload 'https://api.gdc.cancer.gov/files' > response.tsv
{
"filters":{
"op":"and",
"content":[
{
"op":"in",
"content":{
"field":"cases.submitter_id",
"value":[
"TCGA-CK-4948",
"TCGA-D1-A17N",
"TCGA-4V-A9QX",
"TCGA-4V-A9QM"
]
}
},
{
"op":"=",
"content":{
"field":"files.data_type",
"value":"Gene Expression Quantification"
}
}
]
},
"format":"tsv",
"fields":"file_id,file_name,cases.submitter_id,cases.case_id,data_category,data_type,cases.samples.tumor_descriptor,cases.samples.tissue_type,cases.samples.sample_type,cases.samples.submitte
"size":"1000"
}
1.2 Search and Retrieval
- 9/232 -
© 2015-2024
Each component of the request is explained below.
GET Example
The above request can be executed as an HTTP GET:
Each component of the request is explained below.
1.2.2 Endpoints
The following search and retrieval endpoints are available in the GDC API:
The choice of endpoint determines what is listed in the search results. The files endpoint will generate a list of files, whereas the
cases endpoint will generate a list of cases. Each of the above endpoints, other than _mapping , can query and return any of the
related fields in the GDC Data Model. So the cases endpoint can be queried for file fields (e.g. to look for cases that have certain
types of experimental data), and the files endpoint can be queried for clinical metadata associated with a case (e.g. to look for
files from cases diagnosed with a specific cancer type).
Project Endpoint
The projects endpoint provides access to project records, the highest level of data organization in the GDC.
https://api.gdc.cancer.gov/files?
filters=%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22cases.submitter_id%22%2C%22value%22%3A%5B%22TCGA-
CK-4948%22%2C%22TCGA-D1-A17N%22%2C%22TCGA-4V-A9QX%22%2C%22TCGA-4V-
A9QM%22%5D%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22files.data_type%22%2C%22value%22%3A%22Gene%20Expression%20Quantification%22%7D%7D%5D%7D&format=tsv&fields=fil
Endpoints Description
files Information about files stored in the GDC
cases Information related to cases, or sample donors
history Information related to file version history
projects Information about projects
annotations Information about annotations to GDC data
_mapping Information about elements that can be used to query other endpoints
1.2.2 Endpoints
- 10/232 -
© 2015-2024
EXAMPLE
This example is a query for projects contained in the GDC. It uses the from, size, sort, and pretty parameters, and returns the first
two projects sorted by project id.
Shell Output
curl
'https://api.gdc.cancer.gov/projects?from=0&size=2&sort=project_id:asc&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"id"
:
"APOLLO-LUAD"
,
"primary_site"
:
[
"Bronchus and lung"
],
"dbgap_accession_number"
:
"phs003011"
,
"project_id"
:
"APOLLO-LUAD"
,
"disease_type"
:
[
"Adenomas and Adenocarcinomas"
],
"name"
:
"APOLLO1: Proteogenomic characterization of lung adenocarcinoma"
,
"releasable"
:
false
,
"state"
:
"open"
,
"released"
:
true
},
{
"id"
:
"BEATAML1.0-COHORT"
,
"primary_site"
:
[
"Hematopoietic and reticuloendothelial systems"
],
"dbgap_accession_number"
:
"phs001657"
,
"project_id"
:
"BEATAML1.0-COHORT"
,
"disease_type"
:
[
"Myelodysplastic Syndromes"
,
"Leukemias, NOS"
,
"Unknown"
,
"Myeloid Leukemias"
,
"Plasma Cell Tumors"
,
"Chronic Myeloproliferative Disorders"
],
"name"
:
"Functional Genomic Landscape of Acute Myeloid Leukemia"
,
"releasable"
:
true
,
"state"
:
"open"
,
"released"
:
true
}
],
"pagination"
:
{
"count"
:
2
,
"total"
:
78
,
"size"
:
2
,
"from"
:
0
,
"sort"
:
"None"
,
"page"
:
1
,
"pages"
:
39
}
},
"warnings"
:
{}
}
1.2.2 Endpoints
- 11/232 -
© 2015-2024
RETRIEVAL OF PROJECT METADATA USING PROJECT_ID
The project endpoint supports a simple query format that retrieves the metadata of a single project using its project_id :
1.2.2 Endpoints
- 12/232 -
© 2015-2024
Shell Response
curl
'https://api.gdc.cancer.gov/projects/TARGET-NBL?expand=summary,summary.experimental_strategies,summary.data_categories&pretty=true'
{
"data"
:
{
"summary"
:
{
"file_count"
:
5705
,
"data_categories"
:
[
{
"file_count"
:
943
,
"case_count"
:
278
,
"data_category"
:
"Sequencing Reads"
},
{
"file_count"
:
3080
,
"case_count"
:
220
,
"data_category"
:
"Simple Nucleotide Variation"
},
{
"file_count"
:
3
,
"case_count"
:
1119
,
"data_category"
:
"Clinical"
},
{
"file_count"
:
705
,
"case_count"
:
225
,
"data_category"
:
"DNA Methylation"
},
{
"file_count"
:
2
,
"case_count"
:
1132
,
"data_category"
:
"Biospecimen"
},
{
"file_count"
:
324
,
"case_count"
:
155
,
"data_category"
:
"Transcriptome Profiling"
},
{
"file_count"
:
648
,
"case_count"
:
155
,
"data_category"
:
"Structural Variation"
}
],
"experimental_strategies"
:
[
{
"file_count"
:
1458
,
"case_count"
:
155
,
"experimental_strategy"
:
"RNA-Seq"
},
{
"file_count"
:
15
,
"case_count"
:
8
,
"experimental_strategy"
:
"WGS"
},
{
"file_count"
:
3522
,
"case_count"
:
222
,
"experimental_strategy"
:
"WXS"
},
{
"file_count"
:
705
,
"case_count"
:
225
,
"experimental_strategy"
:
"Methylation Array"
}
],
"case_count"
:
1132
,
"file_size"
:
16968781125824
},
"primary_site"
:
[
"Stomach"
,
"Bones, joints and articular cartilage of limbs"
,
"Heart, mediastinum, and pleura"
,
"Peripheral nerves and autonomic nervous system"
,
"Uterus, NOS"
,
"Bones, joints and articular cartilage of other and unspecified sites"
,
"Other endocrine glands and related structures"
,
"Renal pelvis"
,
"Retroperitoneum and peritoneum"
,
"Liver and intrahepatic bile ducts"
,
"Meninges"
,
"Connective, subcutaneous and other soft tissues"
,
"Adrenal gland"
,
"Unknown"
,
"Spinal cord, cranial nerves, and other parts of central nervous system"
,
"Skin"
,
"Other and ill-defined sites"
,
"Kidney"
,
"Lymph nodes"
,
"Hematopoietic and reticuloendothelial systems"
],
"dbgap_accession_number"
:
"phs000467"
,
"project_id"
:
"TARGET-NBL"
,
"disease_type"
:
[
"Neuroepitheliomatous Neoplasms"
,
"Not Applicable"
],
"name"
:
"Neuroblastoma"
,
"releasable"
:
true
,
"state"
:
"open"
,
"released"
:
true
},
1.2.2 Endpoints
- 13/232 -
© 2015-2024
Files Endpoint
The GDC Files Endpoint https://api.gdc.cancer.gov/files enables search and retrieval of information relating to files stored in the
GDC, including file properties such as file_name , md5sum , data_format , and others.
EXAMPLE
This example is a query for files contained in the GDC. It uses the from, size, sort, and pretty parameters, and returns only the first
two files, sorted by file size, from smallest to largest.
Shell Output
curl
'https://api.gdc.cancer.gov/files?from=0&size=2&sort=file_size:asc&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"id"
:
"0ab5e358-b1ff-4433-8959-c37c5890d9aa"
,
"data_format"
:
"BEDPE"
,
"access"
:
"controlled"
,
"file_name"
:
"090e2828-079c-48e6-97cb-735c763da8d3.wgs.BRASS.rerun_structural_variation.bedpe.gz"
,
"submitter_id"
:
"247c3c9a-58b9-4b70-bda8-cb197acb5609"
,
"data_category"
:
"Somatic Structural Variation"
,
"acl"
:
[
"phs001287"
],
"type"
:
"structural_variation"
,
"file_size"
:
20
,
"created_datetime"
:
"2022-04-08T20:27:04.633842-05:00"
,
"updated_datetime"
:
"2022-07-07T11:02:27.204310-05:00"
,
"file_id"
:
"0ab5e358-b1ff-4433-8959-c37c5890d9aa"
,
"data_type"
:
"Structural Rearrangement"
,
"state"
:
"released"
,
"experimental_strategy"
:
"WGS"
,
"version"
:
"1"
,
"data_release"
:
"34.0 - 37.0"
},
{
"id"
:
"a8bc2405-b57d-48bb-b241-18b3e28caa56"
,
"data_format"
:
"BEDPE"
,
"access"
:
"controlled"
,
"file_name"
:
"eae76f14-8aa7-427f-a90c-4e0ed095e0c2.wgs.BRASS.rerun_structural_variation.bedpe.gz"
,
"submitter_id"
:
"618cd251-ddcb-4a7e-9a6d-efb132b0bd7a"
,
"data_category"
:
"Somatic Structural Variation"
,
"acl"
:
[
"phs001287"
],
"type"
:
"structural_variation"
,
"file_size"
:
20
,
"created_datetime"
:
"2022-04-08T20:43:16.505747-05:00"
,
"updated_datetime"
:
"2022-07-07T11:00:43.345766-05:00"
,
"file_id"
:
"a8bc2405-b57d-48bb-b241-18b3e28caa56"
,
"data_type"
:
"Structural Rearrangement"
,
"state"
:
"released"
,
"experimental_strategy"
:
"WGS"
,
"version"
:
"1"
,
"data_release"
:
"34.0 - 37.0"
}
],
"pagination"
:
{
"count"
:
2
,
"total"
:
931947
,
"size"
:
2
,
"from"
:
0
,
"sort"
:
"None"
,
"page"
:
1
,
"pages"
:
465974
}
},
"warnings"
:
{}
}
1.2.2 Endpoints
- 14/232 -
© 2015-2024
RETRIEVAL OF FILE METADATA USING INDIVIDUAL UUIDS:
The /files endpoint supports a simple query format that retrieves the metadata of a single file using its UUID. Note that the /
files endpoint is inactive when querying for earlier file versions. In that case, the /history or /files/versions endpoints should be
used instead.
Note: The
file_size field associated with each file is reported in bytes.
EXAMPLE OF RETRIEVING FILE VERSION INFORMATION:
The https://api.gdc.cancer.gov/files/versions endpoint enables search and retrieval of version information about a file. A file may
be versioned if a file is updated by the GDC (e.g. using a new alignment algorithm or fixing a file that contained an error). Version
refers to the instance of a particular file. Inputs can either be a list of UUIDs as shown in example 1 or a download manifest as
shown in example 2. Output includes information about the current and latest version for any given file. While /files also returns
information about a file version this endpoint will only work for the most recent version of a file whereas /files/versions will work
for all previous and current versions of a file. In both examples below the output format can be modified by adding the format=tsv
parameter.
Shell Output
curl
'https://api.gdc.cancer.gov/files/20f45e04-3c10-4f11-b57b-719880eab69e?pretty=true'
{
"data"
:
{
"data_format"
:
"VCF"
,
"access"
:
"controlled"
,
"file_name"
:
"TCGA_BRCA.8d9cb5ae-e568-41fc-8b53-14467c2623dc.wxs.MuTect2.somatic_annotation.vcf.gz"
,
"submitter_id"
:
"675f31dd-70e5-4a72-8139-423b14b31564"
,
"data_category"
:
"Simple Nucleotide Variation"
,
"acl"
:
[
"phs000178"
],
"type"
:
"annotated_somatic_mutation"
,
"file_size"
:
6894331
,
"created_datetime"
:
"2022-02-07T08:48:39.178606-06:00"
,
"updated_datetime"
:
"2022-02-09T12:11:12.781445-06:00"
,
"file_id"
:
"20f45e04-3c10-4f11-b57b-719880eab69e"
,
"data_type"
:
"Annotated Somatic Mutation"
,
"state"
:
"released"
,
"experimental_strategy"
:
"WXS"
,
"version"
:
"2"
,
"data_release"
:
"32.0 - 37.0"
},
"warnings"
:
{}
}
1.2.2 Endpoints
- 15/232 -
© 2015-2024
1.2.2 Endpoints
- 16/232 -
© 2015-2024
Shell1 Output1 Shell2 Output2
curl
'https://api.gdc.cancer.gov/files/versions/1dd28069-5777-4ff9-bd2b-d1ba68e88b06,2a03abac-f1a2-49a9-a57c-7543739dd862?pretty=true'
[
{
"id"
:
"1dd28069-5777-4ff9-bd2b-d1ba68e88b06"
,
"filename"
:
"1dd28069-5777-4ff9-bd2b-d1ba68e88b06.vcf.gz"
,
"version"
:
"1"
,
"md5"
:
"c2f9b196e154906a70c7ec46492a859d"
,
"size"
:
332092
,
"state"
:
"validated"
,
"release"
:
"12.0"
,
"latest_id"
:
"76b3f4d8-c6b7-4662-ac42-1d27d4684281"
,
"latest_filename"
:
"def1cc5b-55f0-4372-a3ff-df3ea93cf3e7.wxs.somaticsniper.raw_somatic_mutation.vcf.gz"
,
"latest_version"
:
"2"
,
"latest_size"
:
357706
,
"latest_state"
:
"validated"
,
"latest_release"
:
[
"32.0"
,
"33.0"
,
"33.1"
,
"34.0"
,
"35.0"
,
"36.0"
,
"37.0"
]
},
{
"id"
:
"2a03abac-f1a2-49a9-a57c-7543739dd862"
,
"filename"
:
"a5d86cde-32ca-4ed6-b1a5-5a47575f2ac6_gdc_realn_rehead.bam"
,
"version"
:
"1"
,
"md5"
:
"48686fcd84ac713d44261ca9e26b89fb"
,
"size"
:
6653119038
,
"state"
:
"validated"
,
"release"
:
"12.0"
,
"latest_id"
:
"de0ce84d-c286-405c-a556-39dac14c7c74"
,
"latest_filename"
:
"d45c33cc-88e2-4de5-a578-f7e31a6c0738.rna_seq.genomic.gdc_realn.bam"
,
"latest_version"
:
"2"
,
"latest_size"
:
6223445806
,
"latest_state"
:
"validated"
,
"latest_release"
:
[
"32.0"
,
"33.0"
,
"33.1"
,
"34.0"
,
"35.0"
,
"36.0"
,
"37.0"
]
}
]
curl
--request
POST
--header
"Content-Type: text/tsv"
https://api.gdc.cancer.gov/files/versions/manifest?pretty
=
true
--data-binary
@gdc_manifest_20180809_154816.txt
[
{
"id"
:
"0b20e27c-9a09-4f15-923f-d5b4f185dc22"
,
"filename"
:
"nationwidechildrens.org_clinical.TCGA-13-1500.xml"
,
"version"
:
"1"
,
"md5"
:
"597aa4df24c4d544b6c25cbd8b25a33e"
,
"size"
:
44857
,
"state"
:
"validated"
,
"release"
:
"12.0"
,
"latest_id"
:
"0b20e27c-9a09-4f15-923f-d5b4f185dc22"
,
"latest_filename"
:
"nationwidechildrens.org_clinical.TCGA-13-1500.xml"
,
"latest_version"
:
"1"
,
"latest_md5"
:
"597aa4df24c4d544b6c25cbd8b25a33e"
,
"latest_size"
:
44857
,
"latest_state"
:
"validated"
,
"latest_release"
:
[
"12.0"
,
"13.0"
,
"14.0"
,
"15.0"
,
"16.0"
,
"17.0"
,
"18.0"
,
"19.0"
,
"20.0"
,
"21.0"
,
"22.0"
,
"23.0"
,
"24.0"
,
"25.0"
,
"26.0"
,
"27.0"
,
"28.0"
,
"29.0"
,
"30.0"
,
"31.0"
,
"32.0"
,
"33.0"
,
"33.1"
,
"34.0"
,
"35.0"
,
"36.0"
,
"37.0"
]
},
{
"id"
:
"3edc7084-013c-4493-8507-c00b0e9962d8"
,
"filename"
"BUCKS_p_TCGA_272_273_N_GenomeWideSNP_6_G05_1320676.grch38.seg.v2.txt"
1.2.2 Endpoints
- 17/232 -
© 2015-2024
Cases Endpoint
The GDC Cases Endpoint https://api.gdc.cancer.gov/cases enables search and retrieval of information related to a specific case.
The cases endpoint is designed to retrieve the metadata associated with one or more cases, including all nested biospecimen
entities. Filters can be applied to retrieve information for entire cases, but not for lower-level biospecimen entities. For example, a
sample within a case cannot be used to query for aliquots that are associated only with that sample. All aliquots associated with the
case would be retrieved.
EXAMPLE
This example is a query for files contained in GDC. It returns case where submitter id is TCGA-BH-A0EA , using the pretty and filters
parameters and the following filtering operators:
{"op":"and","content":[{"op":"in","content":{"field":"submitter_id","value":["TCGA-BH-A0EA"]}}]}
1.2.2 Endpoints
- 18/232 -
© 2015-2024
Command:
1.2.2 Endpoints
- 19/232 -
© 2015-2024
1.2.2 Endpoints
- 20/232 -
© 2015-2024
Shell Output
curl
'https://api.gdc.cancer.gov/cases?
filters=%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22submitter_id%22%2C%22value%22%3A%5B%22TCGA-BH-
A0EA%22%5D%7D%7D%5D%7D%0A%0A&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"id"
:
"1f601832-eee3-48fb-acf5-80c4a454f26e"
,
"slide_ids"
:
[
"a0826f0d-986a-491b-8c6f-b34f8929f3ee"
,
"90154ea1-6b76-4445-870e-d531d6fa1239"
,
"1dd1cab5-5a81-428a-8153-91e8c4cf9905"
],
"submitter_slide_ids"
:
[
"TCGA-BH-A0EA-01Z-00-DX1"
,
"TCGA-BH-A0EA-01A-01-MSA"
,
"TCGA-BH-A0EA-01A-01-TSA"
],
"disease_type"
:
"Ductal and Lobular Neoplasms"
,
"analyte_ids"
:
[
"f19f408a-815f-43d9-8032-e9482b796371"
,
"fe678556-acf4-4bde-a95e-860bb0150a95"
,
"69ddc092-88a0-4839-a2bb-9f1c9e760409"
,
"66ed0f86-5ca5-4dec-ba76-7ee4dcf31831"
,
"30cb470f-66d4-4085-8c30-83a42e8453d4"
],
"submitter_id"
:
"TCGA-BH-A0EA"
,
"submitter_analyte_ids"
:
[
"TCGA-BH-A0EA-10A-01D"
,
"TCGA-BH-A0EA-01A-11D"
,
"TCGA-BH-A0EA-01A-11R"
,
"TCGA-BH-A0EA-10A-01W"
,
"TCGA-BH-A0EA-01A-11W"
],
"aliquot_ids"
:
[
"cde982b7-3b0a-49eb-8710-a599cb0e44c1"
,
"b1a3739d-d554-4202-b96f-f25a444e2042"
,
"eef9dce1-6ba6-432b-bbe2-53c7dbe64fe7"
,
"97c64d6a-7dce-4d0f-9cb3-b3e4eb4719c5"
,
"262715e1-835c-4f16-8ee7-6900e26f7cf5"
,
"cfbd5476-e83a-401d-9f9a-639c73a0e35b"
,
"bcb7fc6d-60a0-48b7-aa81-14c0dda72d76"
,
"561b8777-801a-49ed-a306-e7dafeb044b6"
,
"edad5bd3-efe0-4c5f-b05c-2c0c2951c45a"
,
"42d050e4-e8ee-4442-b9c0-0ee14706b138"
,
"2beb34c4-d493-4a73-b21e-de77d43251ff"
,
"ca71ca96-cbb7-4eab-9487-251dda34e107"
],
"submitter_aliquot_ids"
:
[
"TCGA-BH-A0EA-10A-01W-A12U-09"
,
"TCGA-BH-A0EA-01A-11D-A111-01"
,
"TCGA-BH-A0EA-01A-11D-A314-09"
,
"TCGA-BH-A0EA-01A-11D-A10X-02"
,
"TCGA-BH-A0EA-10A-01D-A10Z-02"
,
"TCGA-BH-A0EA-10A-01D-A110-09"
,
"TCGA-BH-A0EA-01A-11D-A10Y-09"
,
"TCGA-BH-A0EA-10A-01D-A113-01"
,
"TCGA-BH-A0EA-01A-11D-A112-05"
,
"TCGA-BH-A0EA-01A-11R-A115-07"
,
"TCGA-BH-A0EA-01A-11W-A12T-09"
,
"TCGA-BH-A0EA-01A-11R-A114-13"
],
"created_datetime"
:
null
,
"diagnosis_ids"
:
[
"84654ad5-2a2c-5c3b-8340-ecac6a5550fe"
],
"sample_ids"
:
[
"55864d86-dab8-47bb-a3e3-8cfb198b06c1"
,
"9a6c71a6-82cd-42b1-a93f-f569370848d6"
,
"7f791228-dd77-4ab0-8227-d784a4c7fea1"
],
"submitter_sample_ids"
:
[
"TCGA-BH-A0EA-01A"
,
"TCGA-BH-A0EA-01Z"
,
"TCGA-BH-A0EA-10A"
],
"primary_site"
:
"Breast"
,
"submitter_diagnosis_ids"
:
[
"TCGA-BH-A0EA_diagnosis"
],
"updated_datetime"
:
"2019-08-06T14:15:54.128069-05:00"
,
"case_id"
:
"1f601832-eee3-48fb-acf5-80c4a454f26e"
,
"state"
:
"released"
,
"portion_ids"
:
[
"cb6086d1-3416-4310-b109-e8fa6e8b72d4"
,
"8629bf5a-cdaf-4f6a-90bb-27dd4a7565c5"
,
"ae4f5816-f97a-4605-9b05-9ab820467dee"
],
"submitter_portion_ids"
:
[
"TCGA-BH-A0EA-10A-01"
,
"TCGA-BH-A0EA-01A-21-A13C-20"
,
"TCGA-BH-A0EA-01A-11"
]
}
],
"pagination"
:
{
"count"
:
1
,
"total"
:
1
,
"size"
:
10
,
"from"
:
0
1.2.2 Endpoints
- 21/232 -
© 2015-2024
RETRIEVAL OF CASE METADATA USING INDIVIDUAL UUIDS:
The cases endpoint supports a simple query format that retrieves the metadata of a single case using its UUID:
1.2.2 Endpoints
- 22/232 -
© 2015-2024
1.2.2 Endpoints
- 23/232 -
© 2015-2024
Shell Response
curl
'https://api.gdc.cancer.gov/cases/1f601832-eee3-48fb-acf5-80c4a454f26e?pretty=true&expand=diagnoses'
"data"
:
{
"slide_ids"
:
[
"90154ea1-6b76-4445-870e-d531d6fa1239"
,
"1dd1cab5-5a81-428a-8153-91e8c4cf9905"
,
"a0826f0d-986a-491b-8c6f-b34f8929f3ee"
],
"submitter_slide_ids"
:
[
"TCGA-BH-A0EA-01A-01-MSA"
,
"TCGA-BH-A0EA-01A-01-TSA"
,
"TCGA-BH-A0EA-01Z-00-DX1"
],
"disease_type"
:
"Ductal and Lobular Neoplasms"
,
"analyte_ids"
:
[
"fe678556-acf4-4bde-a95e-860bb0150a95"
,
"66ed0f86-5ca5-4dec-ba76-7ee4dcf31831"
,
"30cb470f-66d4-4085-8c30-83a42e8453d4"
,
"69ddc092-88a0-4839-a2bb-9f1c9e760409"
,
"f19f408a-815f-43d9-8032-e9482b796371"
],
"submitter_id"
:
"TCGA-BH-A0EA"
,
"submitter_analyte_ids"
:
[
"TCGA-BH-A0EA-01A-11D"
,
"TCGA-BH-A0EA-01A-11R"
,
"TCGA-BH-A0EA-10A-01W"
,
"TCGA-BH-A0EA-01A-11W"
,
"TCGA-BH-A0EA-10A-01D"
],
"aliquot_ids"
:
[
"eef9dce1-6ba6-432b-bbe2-53c7dbe64fe7"
,
"2beb34c4-d493-4a73-b21e-de77d43251ff"
,
"b1a3739d-d554-4202-b96f-f25a444e2042"
,
"262715e1-835c-4f16-8ee7-6900e26f7cf5"
,
"cfbd5476-e83a-401d-9f9a-639c73a0e35b"
,
"edad5bd3-efe0-4c5f-b05c-2c0c2951c45a"
,
"bcb7fc6d-60a0-48b7-aa81-14c0dda72d76"
,
"42d050e4-e8ee-4442-b9c0-0ee14706b138"
,
"97c64d6a-7dce-4d0f-9cb3-b3e4eb4719c5"
,
"561b8777-801a-49ed-a306-e7dafeb044b6"
,
"ca71ca96-cbb7-4eab-9487-251dda34e107"
,
"cde982b7-3b0a-49eb-8710-a599cb0e44c1"
],
"submitter_aliquot_ids"
:
[
"TCGA-BH-A0EA-01A-11R-A115-07"
,
"TCGA-BH-A0EA-01A-11D-A112-05"
,
"TCGA-BH-A0EA-10A-01W-A12U-09"
,
"TCGA-BH-A0EA-01A-11D-A10X-02"
,
"TCGA-BH-A0EA-10A-01D-A113-01"
,
"TCGA-BH-A0EA-10A-01D-A110-09"
,
"TCGA-BH-A0EA-01A-11D-A314-09"
,
"TCGA-BH-A0EA-01A-11D-A10Y-09"
,
"TCGA-BH-A0EA-01A-11D-A111-01"
,
"TCGA-BH-A0EA-10A-01D-A10Z-02"
,
"TCGA-BH-A0EA-01A-11R-A114-13"
,
"TCGA-BH-A0EA-01A-11W-A12T-09"
],
"diagnoses"
:
[
{
"synchronous_malignancy"
:
"Not Reported"
,
"ajcc_pathologic_stage"
:
"Stage IIA"
,
"days_to_diagnosis"
:
0
,
"created_datetime"
:
null
,
"last_known_disease_status"
:
"not reported"
,
"tissue_or_organ_of_origin"
:
"Breast, NOS"
,
"days_to_last_follow_up"
:
null
,
"age_at_diagnosis"
:
26548
,
"primary_diagnosis"
:
"Infiltrating duct carcinoma, NOS"
,
"updated_datetime"
:
"2019-08-08T16:25:42.215495-05:00"
,
"prior_malignancy"
:
"yes"
,
"year_of_diagnosis"
:
2008
,
"state"
:
"released"
,
"prior_treatment"
:
"No"
,
"days_to_last_known_disease_status"
:
null
,
"ajcc_staging_system_edition"
:
"6th"
,
"ajcc_pathologic_t"
:
"T1c"
,
"days_to_recurrence"
:
null
,
"morphology"
:
"8500/3"
,
"ajcc_pathologic_n"
:
"N1a"
,
"ajcc_pathologic_m"
:
"M0"
,
"submitter_id"
:
"TCGA-BH-A0EA_diagnosis"
,
"classification_of_tumor"
:
"not reported"
,
"diagnosis_id"
:
"84654ad5-2a2c-5c3b-8340-ecac6a5550fe"
,
"icd_10_code"
:
"C50.9"
,
"site_of_resection_or_biopsy"
:
"Breast, NOS"
,
"tumor_grade"
:
"Not Reported"
,
"progression_or_recurrence"
:
"not reported"
}
],
"created_datetime"
:
null
,
"diagnosis_ids"
:
[
"84654ad5-2a2c-5c3b-8340-ecac6a5550fe"
],
"sample_ids"
:
[
"55864d86-dab8-47bb-a3e3-8cfb198b06c1"
,
"7f791228-dd77-4ab0-8227-d784a4c7fea1"
,
"9a6c71a6-82cd-42b1-a93f-f569370848d6"
],
"submitter_sample_ids"
:
[
"TCGA-BH-A0EA-01A"
,
"TCGA-BH-A0EA-01Z"
1.2.2 Endpoints
- 24/232 -
© 2015-2024
Annotations Endpoint
The GDC Annotation Endpoint https://api.gdc.cancer.gov/annotations enables search and retrieval of annotations stored in the
GDC.
EXAMPLE
This example is a query for any annotations directly associated with the following GDC entities:
• the case with UUID e0d36cc0-652c-4224-bb10-09d15c7bd8f1
• the sample with UUID 25ebc29a-7598-4ae4-ba7f-618d448882cc
• the aliquot with UUID fe660d7c-2746-4b50-ab93-b2ed99960553
The query uses the filters parameter to specify entity UUIDs. Code samples below include the bare and percent-encoded filter
JSON.
1.2.2 Endpoints
- 25/232 -
© 2015-2024
Filter-json Filter-JSON-percent-encoded Shell Output
{
"op"
:
"in"
,
"content"
:{
"field"
:
"entity_id"
,
"value"
:[
"e0d36cc0-652c-4224-bb10-09d15c7bd8f1"
,
"25ebc29a-7598-4ae4-ba7f-618d448882cc"
,
"fe660d7c-2746-4b50-ab93-b2ed99960553"
]
}
}
%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22entity_id%22%2C%22value%22%3A%5B%22e0d36cc0-652c-4224-bb10-09d15c7bd8f1%22%2C%2225ebc29a-7598-4ae4-
ba7f-618d448882cc%22%2C%22fe660d7c-2746-4b50-ab93-b2ed99960553%22%5D%7D%7D
curl
'https://api.gdc.cancer.gov/annotations?
filters=%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22entity_id%22%2C%22value%22%3A%5B%22e0d36cc0-652c-4224-
bb10-09d15c7bd8f1%22%2C%2225ebc29a-7598-4ae4-ba7f-618d448882cc%22%2C%22fe660d7c-2746-4b50-ab93-b2ed99960553%22%5D%7D%7D&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"category"
:
"Item flagged DNU"
,
"status"
:
"Approved"
,
"entity_id"
:
"fe660d7c-2746-4b50-ab93-b2ed99960553"
,
"classification"
:
"CenterNotification"
,
"entity_type"
:
"aliquot"
,
"created_datetime"
:
"2015-09-28T00:00:00"
,
"annotation_id"
:
"5ddadefe-8b57-5ce2-b8b2-918d63d99a59"
,
"notes"
:
"The aliquot failed Broad pipeline QC and not all files are suitable for use. Consult the SDRF file to determine which files are usable."
,
"updated_datetime"
:
"2017-03-09T13:20:38.962182-06:00"
,
"submitter_id"
:
"29087"
,
"state"
:
"submitted"
,
"case_id"
:
"41b59716-116f-4942-8b63-409870a87e26"
,
"case_submitter_id"
:
"TCGA-DK-A3IM"
,
"entity_submitter_id"
:
"TCGA-DK-A3IM-10A-01D-A20B-01"
,
"id"
:
"5ddadefe-8b57-5ce2-b8b2-918d63d99a59"
},
{
"category"
:
"Item is noncanonical"
,
"status"
:
"Approved"
,
"entity_id"
:
"25ebc29a-7598-4ae4-ba7f-618d448882cc"
,
"classification"
:
"Notification"
,
"entity_type"
:
"sample"
,
"created_datetime"
:
"2012-07-12T00:00:00"
,
"annotation_id"
:
"d6500f94-618f-5334-a810-ade76b887ec9"
,
"notes"
:
"No Matching Normal"
,
"updated_datetime"
:
"2017-03-09T13:47:18.182075-06:00"
,
"submitter_id"
:
"8009"
,
"state"
:
"submitted"
,
"case_id"
:
"bd114e05-5a97-41e2-a0d5-5d39a1e9d461"
,
"case_submitter_id"
:
"TCGA-08-0514"
,
"entity_submitter_id"
:
"TCGA-08-0514-01A"
,
"id"
:
"d6500f94-618f-5334-a810-ade76b887ec9"
},
{
"category"
:
"Prior malignancy"
,
"status"
:
"Approved"
,
"entity_id"
:
"e0d36cc0-652c-4224-bb10-09d15c7bd8f1"
,
"classification"
:
"Notification"
,
"entity_type"
:
"case"
,
"created_datetime"
:
"2013-03-12T00:00:00"
,
"annotation_id"
:
"33336cdf-2cf0-5af2-bb52-fecd3427f180"
,
"notes"
:
"Patient had a prior lymphoma. Unknown radiation or systemic chemotherapy."
,
"updated_datetime"
:
"2017-03-09T12:11:31.786013-06:00"
,
"submitter_id"
:
"15630"
,
"state"
:
"submitted"
,
"case_id"
:
"e0d36cc0-652c-4224-bb10-09d15c7bd8f1"
,
"case_submitter_id"
:
"TCGA-FS-A1ZF"
,
"entity_submitter_id"
:
"TCGA-FS-A1ZF"
,
"id"
:
"33336cdf-2cf0-5af2-bb52-fecd3427f180"
}
],
"pagination"
:
{
"count"
:
3
,
"sort"
:
""
,
"from"
:
0
,
"page"
:
1
,
"total"
:
3
,
"pages"
:
1
,
"size"
:
10
}
},
"warnings"
:
{}
}
1.2.2 Endpoints
- 26/232 -
© 2015-2024
History Endpoint
The GDC History Endpoint https://api.gdc.cancer.gov/history enables search and retrieval of version and release information
about a file. This endpoint will return the entire provenance of all versions of a file. A file may be versioned if a file is updated by
the GDC (e.g. using a new alignment algorithm or fixing a file that contained an error). Version refers to the instance of a
particular file. Release refers to which data release a file was part of. A file may be a part of many different data releases with no
change in version number or content.
EXAMPLE
This example is a query for versioning information associated with the follow with file 1dd28069-5777-4ff9-bd2b-d1ba68e88b06 .
_mapping Endpoint
Each search and retrieval endpoint is equipped with a _mapping endpoint that provides information about available fields. For
example, files/_mapping endpoint provides information about fields and field groups available at the files endpoint: https://
api.gdc.cancer.gov/files/_mapping .
The high-level structure of a response to a _mapping query is as follows:
Each part of the response is described below:
Shell Output
curl
'https://api.gdc.cancer.gov/history/1dd28069-5777-4ff9-bd2b-d1ba68e88b06'
[{
"uuid"
:
"1dd28069-5777-4ff9-bd2b-d1ba68e88b06"
,
"version"
:
"1"
,
"file_change"
:
"superseded"
,
"release_date"
:
"2018-08-23"
,
"data_release"
:
"12.0"
},
{
"uuid"
:
"76b3f4d8-c6b7-4662-ac42-1d27d4684281"
,
"version"
:
"2"
,
"file_change"
:
"released"
,
"release_date"
:
"2022-03-29"
,
"data_release"
:
"32.0"
}]
"_mapping": {}
, "defaults": []
, "expand": []
, "fields": []
, "multi": []
, "nested": []
Part Description
_mapping All available fields and their descriptions. The endpoint-agnostic field names provided here are compatible
with the filters parameter but are not always compatible with the fields parameter
defaults The default set of fields included in the API response when the fields parameter is not used in the request
expand Field group names for use with the expand parameter
fields All available fields in an endpoint-specific format that is compatible with both the filters and fields
parameters
multi GDC internal use
nested Nested fields
1.2.2 Endpoints
- 27/232 -
© 2015-2024
EXAMPLE
Similar information can be obtained using the fields parameter; fields queries provide additional information in the response,
such as the name of the Elastic Search document ( doc_type ), the field name and the type of value. A list of supported types (such
as string , long , float , ...) can be obtained from Elastic Search Documentation.
1.2.3 Request Parameters
The GDC API supports the following search & retrieval request parameters:
Filters: Specifying the Query
The filters parameter enables passing of complex search queries to the GDC API. The parameter carries a query in the form of a
JSON object.
QUERY FORMAT
A filters query consists of an operator (or a nested set of operators) with a set of field and value operands.
Shell Output
curl
'https://api.gdc.cancer.gov/projects/_mapping'
This
ou
t
pu
t
was
pu
t
t
hough
t
a
jso
n
f
orma
t
applica
t
io
n
f
or
easier
viewabili
t
y.
{
...
"_mapping"
:
{
"projects.disease_type"
:
{
"doc_type"
:
"projects"
,
"field"
:
"disease_type"
,
"type"
:
"id"
},
"projects.name"
:
{
"doc_type"
:
"projects"
,
"field"
:
"name"
,
"type"
:
"id"
}
}
...
}
Parameter Default Description
filters null Specifies search parameters
format JSON Specifies the API response format: JSON, XML, or TSV
pretty false Returns response with indentations and line breaks in a human-readable format
fields null Specifies which fields to include in the response
expand null Returns multiple related fields
size 10 Specifies the number of results to return
from 0 Specifies the first record to return from a set of search results
sort null Specifies sorting for the search results
facets null Provides all existing values for a given field and the number of records having this
value.
1.2.3 Request Parameters
- 28/232 -
© 2015-2024
The following filters query operators are supported by the GDC API:
The field operand specifies a field that corresponds to a property defined in the GDC Data Dictionary. A list of supported fields is
provided in Appendix A; the list can also be accessed programmatically at the _mapping endpoint.
The value operand specifies the search terms. Users can get a list of available values for a specific property by making a call to the
appropriate API endpoint using the facets parameter, e.g. https://api.gdc.cancer.gov/v0/cases?
facets=demographic.gender&size=0&pretty=true . See Facets for details.
A simple query with a single operator looks like this:
A more complex query with multiple operators looks like this:
Operator Description Number of
Operands
Logic example
= equals (string or number) one gender = "female"
!= does not equal (string or
number)
one project_id != "TARGET-AML"
< less than (number) one age at diagnosis < 90y
<= less than or equal (number) one age at diagnosis <= 17
> greater than (number) one age at diagnosis > 50
>= greater than or equal
(number)
one age at diagnosis >= 18
is is (missing) one gender is missing
not not (missing) one race not missing
in matches a string or number in
(a list)
multiple primary_site in [Brain, Lung]
exclude does not match any strings or
values in (a list)
multiple experimental_strategy exclude [WXS,
WGS, "Genotyping array"]
and (operation1) and (operation2) multiple {primary_site in [Brain, Lung]} and
{gender = "female"}
or (operation1) or (operation2) multiple {project_id != "TARGET-AML"} or {age at
diagnosis < 90y}
{
"op":"=",
"content":{
"field":"cases.demographic.gender",
"value":[
"male"
]
}
}
{
"op":"and",
"content":[
{
"op":"in",
"content":{
"field":"cases.submitter_id",
"value":[
"TCGA-CK-4948",
"TCGA-D1-A17N",
"TCGA-4V-A9QX",
"TCGA-4V-A9QM"
]
}
},
{
"op":"=",
1.2.3 Request Parameters
- 29/232 -
© 2015-2024
EXAMPLE: HTTP GET REQUEST
This example requests male cases using HTTP GET.
The JSON object to be passed to the GDC API looks like:
URL-encoding the above JSON object using Percent-(URL)-encoding tool results in the following string:
"content":{
"field":"files.data_type",
"value":"Gene Expression Quantification"
}
}
]
}
{
"op": "=",
"content": {
"field": "cases.demographic.gender",
"value": [
"male"
]
}
}
%7B%0D%0A++++%22op%22%3A+%22%3D%22%2C%0D%0A++++%22content%22%3A+%7B%0D%0A++++++++%22field%22%3A+%22cases.demographic.gender%22%2C%0D%0A++++++++%22value%22%3A+%5B%0D%0A+
+++++++++++%22male%22%0D%0A++++++++%5D%0D%0A++++%7D%0D%0A%7D
1.2.3 Request Parameters
- 30/232 -
© 2015-2024
The above string can now be passed to the GDC API using the filters parameter:
1.2.3 Request Parameters
- 31/232 -
© 2015-2024
1.2.3 Request Parameters
- 32/232 -
© 2015-2024
Shell Python Output
curl
'https://api.gdc.cancer.gov/cases?filters=%7b%22op%22%3a+%22%3d%22%2c%0d%0a++++++%22content%22%3a+%7b%0d%0a++++++++++%22field%22%3a+
%22cases.demographic.gender%22%2c%0d%0a++++++++++%22value%22%3a+%5b%22male%22%5d%0d%0a++++++%7d%0d%0a%7d&pretty=true'
import
requests
import
json
cases_endpt
=
'https://api.gdc.cancer.gov/cases'
filt
=
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.demographic.gender"
,
"value"
:
[
"male"
]
}
}
params
=
{
'filters'
:
json
.
dumps
(
filt
),
'sort'
:
'demographic.gender:asc'
}
# requests URL-encodes automatically
response
=
requests
.
get
(
cases_endpt
,
params
=
params
)
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
{
"data"
:
{
"hits"
:
[
{
"id"
:
"03974dc9-0162-4de8-9897-09f88693681a"
,
"lost_to_followup"
:
null
,
"days_to_lost_to_followup"
:
null
,
"disease_type"
:
"Nevi and Melanomas"
,
"analyte_ids"
:
[
"9747b614-624b-410a-8b94-854a16cd143a"
,
"c8974764-4836-4a34-aeb8-52b491f78d0e"
,
"bcea1ed5-b9cb-4a92-ad80-598d8a223fb3"
],
"submitter_id"
:
"HCM-BROD-0334-C43"
,
"submitter_analyte_ids"
:
[
"HCM-BROD-0334-C43-10A-01D"
,
"HCM-BROD-0334-C43-85M-01D"
,
"HCM-BROD-0334-C43-85M-01R"
],
"days_to_consent"
:
null
,
"aliquot_ids"
:
[
"dcd74e48-12f3-4a86-a829-c7e055c215b7"
,
"ea182abf-041d-474a-bc53-f6fdd05cd999"
,
"33f3ba0a-c902-4288-9fa7-5696d959e51d"
],
"submitter_aliquot_ids"
:
[
"HCM-BROD-0334-C43-85M-01R-A79O-41"
,
"HCM-BROD-0334-C43-10A-01D-A79L-36"
,
"HCM-BROD-0334-C43-85M-01D-A79L-36"
],
"created_datetime"
:
"2020-05-21T08:55:40.814734-05:00"
,
"diagnosis_ids"
:
[
"3d666f1b-58c2-451f-8ebf-87b5caa02aaf"
,
"fedc3533-85f7-4fc6-b996-a1f596e021df"
],
"sample_ids"
:
[
"cd88baf4-b6eb-4df5-9b42-d55f3aad739c"
,
"eb79f8b4-1cc3-4a32-ad51-cfea8cf150f0"
],
"consent_type"
:
null
,
"submitter_sample_ids"
:
[
"HCM-BROD-0334-C43-10A"
,
"HCM-BROD-0334-C43-85M"
],
"primary_site"
:
"Skin"
,
"submitter_diagnosis_ids"
:
[
"HCM-BROD-0334-C43_diagnosis2"
,
"HCM-BROD-0334-C43_diagnosis"
],
"updated_datetime"
:
"2021-03-03T15:15:08.075155-06:00"
,
"case_id"
:
"03974dc9-0162-4de8-9897-09f88693681a"
,
"index_date"
:
"Diagnosis"
,
"state"
:
"released"
,
"portion_ids"
:
[
"bd0bc175-5b54-47c1-96fc-c6d8afc0c115"
],
"submitter_portion_ids"
:
[
"HCM-BROD-0334-C43-10A-01"
]
},
{
"id"
:
"03bfeb7c-cecf-4691-8263-33cdfe391ea9"
,
"lost_to_followup"
:
null
,
"days_to_lost_to_followup"
:
null
,
"disease_type"
:
"Adenomas and Adenocarcinomas"
,
"analyte_ids"
:
[
"db8132c3-47a8-49ec-9b78-bc7d18debf67"
,
"f74bf217-dae2-4554-92e4-8707068ea7a7"
,
"01764f17-2a97-442e-a08b-8a21303b4770"
,
"c9884c81-3c8f-4ad9-a962-42c7459a2276"
,
"d4f1a9f8-f748-4f45-aa06-da4d760c4fab"
],
"submitter_id"
:
"HCM-BROD-0124-C25"
,
"submitter_analyte_ids"
:
[
"HCM-BROD-0124-C25-85A-01D"
,
"HCM-BROD-0124-C25-01A-01D"
,
"HCM-BROD-0124-C25-10A-01D"
,
"HCM-BROD-0124-C25-85A-01R"
,
"HCM-BROD-0124-C25-01A-01R"
],
"aliquot_ids"
:
[
"fe8e2565-749a-470a-b843-7afbe95ded81"
,
"092656af-b279-46b8-9ccf-b1eabfbd1d6f"
,
"677edb2c-fac3-4878-a28d-cf4e0d7873d7"
1.2.3 Request Parameters
- 33/232 -
© 2015-2024
EXAMPLE: HTTP POST REQUEST
This example demonstrates how to obtain metadata in TSV format for a set of files using their UUIDs (e.g. UUIDs obtained from a
download manifest file generated by the GDC Data Portal).
1.2.3 Request Parameters
- 34/232 -
© 2015-2024
The first step is to construct a JSON query object, including filters , fields , format , and size parameters. The object is then
submitted as HTTP POST payload to the GDC API using curl, in order to retrieve a TSV file with the requested metadata.
Payload_txt Shell File_metadata_txt
{
"filters"
:{
"op"
:
"in"
,
"content"
:{
"field"
:
"files.file_id"
,
"value"
:[
"0001801b-54b0-4551-8d7a-d66fb59429bf"
,
"002c67f2-ff52-4246-9d65-a3f69df6789e"
,
"003143c8-bbbf-46b9-a96f-f58530f4bb82"
,
"0043d981-3c6b-463f-b512-ab1d076d3e62"
,
"004e2a2c-1acc-4873-9379-ef1aa12283b6"
,
"005239a8-2e63-4ff1-9cd4-714f81837a61"
,
"006b8839-31e5-4697-b912-8e3f4124dd15"
,
"006ce9a8-cf38-462e-bb99-7f08499244ab"
,
"007ce9b5-3268-441e-9ffd-b40d1127a319"
,
"0084a614-780b-42ec-b85f-7a1b83128cd3"
,
"00a5e471-a79f-4d56-8a4c-4847ac037400"
,
"00ab2b5a-b59e-4ec9-b297-76f74ff1d3fb"
,
"00c5f14e-a398-4076-95d1-25f320ee3a37"
,
"00c74a8b-10aa-40cc-991e-3365ea1f3fce"
,
"00df5a50-bce3-4edf-a078-641e54800dcb"
]
}
},
"format"
:
"TSV"
,
"fields"
:
"file_id,file_name,cases.submitter_id,cases.case_id,data_category,data_type,cases.samples.tumor_descriptor,cases.samples.tissue_type,cases.samples.sample_type,cases.samples.submi
"size"
:
"100"
}
curl
--request
POST
--header
"Content-Type: application/json"
--data
@Payload.txt
'https://api.gdc.cancer.gov/files'
>
File_metadata.txt
cases_0_submitter_id cases_0_case_id data_type cases_0_samples_0_sample_type cases_0_samples_0_tissue_type file_name cases_0_samples_0_submitter_id
cases_0_samples_0_portions_0_analytes_0_aliquots_0_aliquot_id cases_0_samples_0_sample_id file_id data_category cases_0_samples_0_tumor_descriptor
cases_0_samples_0_portions_0_analytes_0_aliquots_0_submitter_id
TCGA-B0-5094 8aaa4e25-5c12-4ace-96dc-91aaa0c4457c Aligned Reads Solid Tissue Normal C345.TCGA-B0-5094-11A-01D-1421-08.5_gdc_realn.bam TCGA-
B0-5094-11A b4e4630a-b38c-4b62-b0e8-d73f0e3b4e47 7519d7a8-c3ee-417b-9cfc-111bc5ad0637 0001801b-54b0-4551-8d7a-d66fb59429bf Raw Sequencing Data TCGA-
B0-5094-11A-01D-1421-08
TCGA-B0-5117 ae55b2d3-62a1-419e-9f9a-5ddfac356db4 Aligned Reads Solid Tissue Normal C345.TCGA-B0-5117-11A-01D-1421-08.5_gdc_realn.bam TCGA-
B0-5117-11A 45c68b6b-0bed-424d-9a77-4f87bbaa3649 b1116541-bece-4df3-b3dd-cec50aeb277b 003143c8-bbbf-46b9-a96f-f58530f4bb82 Raw Sequencing Data TCGA-
B0-5117-11A-01D-1421-08
TCGA-G7-6790 e7a1cbe2-793c-4747-8412-8be794f2382b Aligned Reads Blood Derived Normal C489.TCGA-G7-6790-10A-01D-1962-08.2_gdc_realn.bam TCGA-
G7-6790-10A 66cbb40f-14b3-40c0-a332-e8a8e21bca11 4be83d0f-8b09-4e9e-8318-358371d34332 004e2a2c-1acc-4873-9379-ef1aa12283b6 Raw Sequencing Data TCGA-
G7-6790-10A-01D-1962-08
TCGA-B9-A69E a4225cb2-7b4b-4122-b6b9-629c26e3ea56 Aligned Reads Blood Derived Normal TCGA-B9-A69E-10A-01D-A31X-10_Illumina_gdc_realn.bam TCGA-B9-
A69E-10A f4799bdc-b207-4053-9a4b-5a26ebf8ab91 5d6d6cd4-6a7b-499d-936a-1be9bf74b07f 0084a614-780b-42ec-b85f-7a1b83128cd3 Raw Sequencing Data TCGA-B9-
A69E-10A-01D-A31X-10
TCGA-EE-A2GU 24faa36a-268d-4a13-b3ae-eacd431a2bcc Aligned Reads Blood Derived Normal C828.TCGA-EE-A2GU-10A-01D-A198-08.2_gdc_realn.bam TCGA-EE-
A2GU-10A c3feacc2-5a26-4bb2-a312-8b2ee53ccad1 cc4a5ed8-376a-4842-a25d-ffb07d8e1ca0 00c74a8b-10aa-40cc-991e-3365ea1f3fce Raw Sequencing Data TCGA-EE-
A2GU-10A-01D-A198-08
TCGA-CE-A484 e62a728d-390f-428a-bea1-fc8c9814fb11 Aligned Reads Blood Derived Normal C499.TCGA-CE-A484-10A-01D-A23U-08.3_gdc_realn.bam TCGA-CE-
A484-10A 641a0220-6eec-434a-b606-e256113b65da 27a8008e-044a-4966-b518-cc6905e292ca 00df5a50-bce3-4edf-a078-641e54800dcb Raw Sequencing Data TCGA-CE-
A484-10A-01D-A23U-08
TCGA-DA-A1IB 8fc9cc74-f388-49f0-b957-debb62638634 Aligned Reads Blood Derived Normal C828.TCGA-DA-A1IB-10A-01D-A198-08.2_gdc_realn.bam TCGA-DA-
A1IB-10A 30919a1a-df9f-4604-835e-f66ac7bcacdf 432952c5-6505-4220-a581-f65270a45281 00ab2b5a-b59e-4ec9-b297-76f74ff1d3fb Raw Sequencing Data TCGA-DA-
A1IB-10A-01D-A198-08
TCGA-AX-A2HG 7a2cf5ce-8317-4fff-946e-b9937afab815 Aligned Reads Blood Derived Normal 6c2a8ea343da8d6cc0fd2043492f16df_gdc_realn.bam TCGA-AX-
A2HG-10A 8c34ffe2-9012-4b4a-b610-a42a9c6a9780 ef4b80ec-b453-48ec-8ad8-ccac83e1e4db 00c5f14e-a398-4076-95d1-25f320ee3a37 Raw Sequencing Data TCGA-AX-
A2HG-10A-01D-A17D-09
TCGA-EC-A24G b5c1e511-baf2-45b3-9919-110e8941e3c2 Aligned Reads Blood Derived Normal 671333b193812fc2bd2744053b383459_gdc_realn.bam TCGA-EC-
A24G-10A 2a8cb8fe-b64f-453e-8139-7ede12f3fc51 61cf2e54-1b8d-40a0-9c73-a7449cbd570a 00a5e471-a79f-4d56-8a4c-4847ac037400 Raw Sequencing Data TCGA-EC-
A24G-10A-01D-A16D-09
TCGA-B5-A0K0 29c8f468-5ac1-4d6c-8376-e36e6d246926 Aligned Reads Blood Derived Normal TCGA-B5-A0K0-10A-01W-A062-09_IlluminaGA-
DNASeq_exome_gdc_realn.bam TCGA-B5-A0K0-10A 02e65074-ffda-4795-b8f5-1bfd20bd1019 1df69e2e-f392-465f-8e61-4671ba2fcd35 007ce9b5-3268-441e-9ffd-
b40d1127a319 Raw Sequencing Data TCGA-B5-A0K0-10A-01W-A062-09
TCGA-C8-A27B f0d8a1fe-e313-44f1-99cc-b965cbeeff0e Aligned Reads Blood Derived Normal 3c99d98ea8eb6acbf819e67fc77623d9_gdc_realn.bam TCGA-C8-
A27B-10A 922226ba-6244-4953-ad42-f4daa474c288 31139082-7978-45aa-9d8f-ac4789ac5cec 006b8839-31e5-4697-b912-8e3f4124dd15 Raw Sequencing Data TCGA-C8-
A27B-10A-01D-A167-09
TCGA-E9-A295 fec0da58-1047-44d2-b6d1-c18cceed43dc Aligned Reads Blood Derived Normal fd4421a6bbf3efd4e3d5c17fdd610314_gdc_realn.bam TCGA-E9-
A295-10A cd761feb-9a20-4495-8943-c6243532a5cf e74183e1-f0b4-412a-8dac-a62d404add78 002c67f2-ff52-4246-9d65-a3f69df6789e Raw Sequencing Data TCGA-E9-
A295-10A-01D-A16D-09
TCGA-EB-A44O c787c4da-c564-44f1-89eb-dd9da107acb1 Aligned Reads Blood Derived Normal C828.TCGA-EB-A44O-10A-01D-A25O-08.3_gdc_realn.bam TCGA-EB-
A44O-10A c723584a-c404-4c88-bfea-e40f5dbba542 5b738547-1825-4684-81bd-864bf2eb43ef 006ce9a8-cf38-462e-bb99-7f08499244ab Raw Sequencing Data TCGA-EB-
A44O-10A-01D-A25O-08
TCGA-A2-A3XX 53886143-c1c6-40e9-88e6-e4e5e0271fc8 Aligned Reads Blood Derived Normal b40998d4778f18ed80d6dd8bff0eb761_gdc_realn.bam TCGA-A2-
A3XX-10A e96d5811-4736-40dd-966d-e0e172aeb0af c6eb6218-ad71-40a6-88b7-a4f1a015b816 0043d981-3c6b-463f-b512-ab1d076d3e62 Raw Sequencing Data TCGA-A2-
A3XX-10A-01D-A23C-09
TCGA-EB-A3XB a9255dcb-b236-4777-ac43-555e3a5386c3 Aligned Reads Blood Derived Normal C828.TCGA-EB-A3XB-10B-01D-A23B-08.1_gdc_realn.bam TCGA-EB-
A3XB-10B 9f4ffc2f-d006-4d86-b3b1-b25020481893 0e1d4c7c-204d-4765-b090-68ed4cd83835 005239a8-2e63-4ff1-9cd4-714f81837a61 Raw Sequencing Data TCGA-EB-
A3XB-10B-01D-A23B-08
1.2.3 Request Parameters
- 35/232 -
© 2015-2024
Format
Specifies the format of the API response: JSON (default), TSV or XML .
EXAMPLES
Shell1 Python1 Response1 Shell 2 Python2 Output2
curl
'https://api.gdc.cancer.gov/cases?fields=submitter_id&size=5&format=TSV'
import
requests
cases_endpt
=
'https://api.gdc.cancer.gov/cases'
params
=
{
'fields'
:
'submitter_id'
,
'format'
:
'TSV'
}
response
=
requests
.
get
(
cases_endpt
,
params
=
params
)
print
(
response
.
content
)
id submitter_id
0286c31b-a704-4d7d-99e3-0bc4e8975b8b HCM-CSHL-0084-C25
02f6d684-b6b5-419a-b0e1-b74d0a384a30 HCM-BROD-0408-C71
03974dc9-0162-4de8-9897-09f88693681a HCM-BROD-0334-C43
03bfeb7c-cecf-4691-8263-33cdfe391ea9 HCM-BROD-0124-C25
04cbceab-f945-482b-956b-840756a17a4a HCM-BROD-0421-C71
curl
'https://api.gdc.cancer.gov/cases?fields=submitter_id&size=5&format=XML&pretty=true'
import
requests
cases_endpt
=
'https://api.gdc.cancer.gov/cases'
params
=
{
'fields'
:
'submitter_id'
,
'format'
:
'XML'
,
'pretty'
:
'true'
}
response
=
requests
.
get
(
cases_endpt
,
params
=
params
)
print
(
response
.
content
)
<?xml version="1.0" ?>
<response>
<data>
<hits>
<item>
<id>
0286c31b-a704-4d7d-99e3-0bc4e8975b8b
</id>
<submitter_id>
HCM-CSHL-0084-C25
</submitter_id>
</item>
<item>
<id>
02f6d684-b6b5-419a-b0e1-b74d0a384a30
</id>
<submitter_id>
HCM-BROD-0408-C71
</submitter_id>
</item>
<item>
<id>
03974dc9-0162-4de8-9897-09f88693681a
</id>
<submitter_id>
HCM-BROD-0334-C43
</submitter_id>
</item>
<item>
<id>
03bfeb7c-cecf-4691-8263-33cdfe391ea9
</id>
<submitter_id>
HCM-BROD-0124-C25
</submitter_id>
</item>
<item>
<id>
04cbceab-f945-482b-956b-840756a17a4a
</id>
<submitter_id>
HCM-BROD-0421-C71
</submitter_id>
</item>
</hits>
<pagination>
<count>
5
</count>
<total>
86962
</total>
<size>
5
</size>
<from>
0
</from>
<sort/>
<page>
1
</page>
<pages>
17393
</pages>
</pagination>
</data>
<warnings/>
</response>
1.2.3 Request Parameters
- 36/232 -
© 2015-2024
Pretty
Returns when the pretty parameter is set to true , the API response is formatted with additional whitespace to improve legibility.
EXAMPLE
Fields
This query parameter specifies which fields are to be included in the API response. The fields in the API response will be
unordered. A listing of available fields for each endpoint is provided in Appendix A.
Request1 Response1 Request2 Response2
curl
'https://api.gdc.cancer.gov/cases?fields=submitter_id&sort=submitter_id:asc&size=5'
{
"data"
:
{
"hits"
:
[{
"id"
:
"be37f1f7-2f98-4f74-bc04-6dd2ae2afcad"
,
"submitter_id"
:
"01BR001"
},
{
"id"
:
"e6915db0-7c89-484d-8f9f-15cca68b82fc"
,
"submitter_id"
:
"01BR008"
},
{
"id"
:
"16614d46-172b-479c-992b-e80a8e9a2c59"
,
"submitter_id"
:
"01BR009"
},
{
"id"
:
"567fc9e3-17a6-42b1-a896-5e9a9507d1d8"
,
"submitter_id"
:
"01BR010"
},
{
"id"
:
"54e89878-a1bc-4f5a-9d68-4842a469586e"
,
"submitter_id"
:
"01BR015"
}],
"pagination"
:
{
"count"
:
5
,
"total"
:
86962
,
"size"
:
5
,
"from"
:
0
,
"sort"
:
"None"
,
"page"
:
1
,
"pages"
:
17393
}},
"warnings"
:
{}}
curl
'https://api.gdc.cancer.gov/cases?fields=submitter_id&sort=submitter_id:asc&size=5&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"id"
:
"be37f1f7-2f98-4f74-bc04-6dd2ae2afcad"
,
"submitter_id"
:
"01BR001"
},
{
"id"
:
"e6915db0-7c89-484d-8f9f-15cca68b82fc"
,
"submitter_id"
:
"01BR008"
},
{
"id"
:
"16614d46-172b-479c-992b-e80a8e9a2c59"
,
"submitter_id"
:
"01BR009"
},
{
"id"
:
"567fc9e3-17a6-42b1-a896-5e9a9507d1d8"
,
"submitter_id"
:
"01BR010"
},
{
"id"
:
"54e89878-a1bc-4f5a-9d68-4842a469586e"
,
"submitter_id"
:
"01BR015"
}
],
"pagination"
:
{
"count"
:
5
,
"total"
:
86962
,
"size"
:
5
,
"from"
:
0
,
"sort"
:
"None"
,
"page"
:
1
,
"pages"
:
17393
}
},
"warnings"
:
{}
}
1.2.3 Request Parameters
- 37/232 -
© 2015-2024
EXAMPLE
The following example requests case submitter ID, file UUID, file name and file size from the files endpoint.
1.2.3 Request Parameters
- 38/232 -
© 2015-2024
1.2.3 Request Parameters
- 39/232 -
© 2015-2024
Shell Python Response
curl
'https://api.gdc.cancer.gov/files?fields=cases.submitter_id,file_id,file_name,file_size&pretty=true'
import
requests
import
json
files_endpt
=
'https://api.gdc.cancer.gov/files'
params
=
{
'fields'
:
'cases.submitter_id,file_id,file_name,file_size'
}
response
=
requests
.
get
(
files_endpt
,
params
=
params
)
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
{
"data"
:
{
"hits"
:
[
{
"id"
:
"d570eccc-3c1c-4c4f-ae04-96be71fbe016"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-AN-A0FL"
}
],
"file_name"
:
"TCGA-AN-A0FL-01Z-00-DX1.20A041C6-A306-4599-A7D1-65032A252AA9.svs"
,
"file_id"
:
"d570eccc-3c1c-4c4f-ae04-96be71fbe016"
,
"file_size"
:
1055798681
},
{
"id"
:
"0f8d8202-a1ca-4ea1-98b2-c20a6b08479a"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-AN-A0FL"
}
],
"file_name"
:
"nationwidechildrens.org_ssf.TCGA-AN-A0FL.xml"
,
"file_id"
:
"0f8d8202-a1ca-4ea1-98b2-c20a6b08479a"
,
"file_size"
:
15519
},
{
"id"
:
"b76f87b3-99c5-4297-b2df-8cbea8ecaf61"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-BH-A18F"
}
],
"file_name"
:
"7c4e4c2a-a0b1-424f-97d8-359825674429.wxs.aliquot_ensemble_masked.maf.gz"
,
"file_id"
:
"b76f87b3-99c5-4297-b2df-8cbea8ecaf61"
,
"file_size"
:
21571
},
{
"id"
:
"be6d269d-4305-4643-b98e-af703a067761"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-BH-A18F"
}
],
"file_name"
:
"HITCH_p_TCGASNP_b93_N_GenomeWideSNP_6_E11_741424.CEL"
,
"file_id"
:
"be6d269d-4305-4643-b98e-af703a067761"
,
"file_size"
:
69084893
},
{
"id"
:
"fed73119-1d5e-4f7e-9713-183d1916422b"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-BH-A18F"
}
],
"file_name"
:
"3b928f83-14a7-4bd6-a9b0-744b414d4495.wxs.varscan2.raw_somatic_mutation.vcf.gz"
,
"file_id"
:
"fed73119-1d5e-4f7e-9713-183d1916422b"
,
"file_size"
:
35903
},
{
"id"
:
"6877b045-91f1-4030-82ff-b90507e11e17"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-BH-A18F"
}
],
"file_name"
:
"5057e3cb-25cd-4a67-8d31-6ac8508ba3c7.methylation_array.sesame.level3betas.txt"
,
"file_id"
:
"6877b045-91f1-4030-82ff-b90507e11e17"
,
"file_size"
:
770500
},
{
"id"
:
"07e8cdc7-d228-4752-ad19-800abd507277"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-BH-A0BM"
}
],
"file_name"
:
"TCGA-BRCA.28dcad29-448e-4bcb-911d-556c6f4a5573.star_fusion.rna_fusion.tsv"
,
"file_id"
:
"07e8cdc7-d228-4752-ad19-800abd507277"
,
"file_size"
:
234
},
{
"id"
:
"fef57b45-ede1-49b0-b60d-957a55a15e0e"
,
"cases"
:
[
{
"submitter_id"
:
"TCGA-BH-A0BM"
}
],
"file_name"
:
"nationwidechildrens.org_biospecimen.TCGA-BH-A0BM.xml"
,
"file_id"
:
"fef57b45-ede1-49b0-b60d-957a55a15e0e"
,
"file_size"
:
127218
},
1.2.3 Request Parameters
- 40/232 -
© 2015-2024
Expand
The expand parameter provides a shortcut to request multiple related fields (field groups) in the response. Instead of specifying
each field using the fields parameter, users can specify a field group name using the expand parameter to request all fields in the
group. Available field groups are listed in Appendix A; the list can also be accessed programmatically at the _mapping endpoint.
The fields and expand parameters can be used together to request custom combinations of field groups and individual fields.
EXAMPLE
Shell Response
curl
'https://api.gdc.cancer.gov/files/573ee7e9-b8bd-419e-808b-a027c4311731?expand=cases.samples&pretty=true'
{
"data"
:
{
"proportion_reads_mapped"
:
0.9648433596149857
,
"access"
:
"controlled"
,
"proportion_base_mismatch"
:
0.004117986
,
"contamination_error"
:
0
,
"acl"
:
[
"phs000178"
],
"type"
:
"aligned_reads"
,
"platform"
:
"Illumina"
,
"created_datetime"
:
"2022-05-12T14:42:10.014925-05:00"
,
"updated_datetime"
:
"2022-11-01T11:52:54.136033-05:00"
,
"pairs_on_diff_chr"
:
1170013
,
"state"
:
"released"
,
"data_format"
:
"BAM"
,
"total_reads"
:
379313036
,
"proportion_coverage_30x"
:
0.000109
,
"cases"
:
[
{
"samples"
:
[
{
"sample_type_id"
:
"10"
,
"tumor_descriptor"
:
"Not Reported"
,
"sample_id"
:
"4e128a37-be58-477a-a01f-448179360b7c"
,
"sample_type"
:
"Blood Derived Normal"
,
"tumor_code"
:
null
,
"created_datetime"
:
null
,
"time_between_excision_and_freezing"
:
null
,
"composition"
:
"Not Reported"
,
"updated_datetime"
:
"2022-04-28T22:05:09.013808-05:00"
,
"days_to_collection"
:
6755
,
"state"
:
"released"
,
"initial_weight"
:
null
,
"preservation_method"
:
null
,
"intermediate_dimension"
:
null
,
"time_between_clamping_and_freezing"
:
null
,
"freezing_method"
:
null
,
"pathology_report_uuid"
:
null
,
"submitter_id"
:
"TCGA-B6-A0RI-10A"
,
"tumor_code_id"
:
null
,
"shortest_dimension"
:
null
,
"oct_embedded"
:
"false"
,
"days_to_sample_procurement"
:
null
,
"longest_dimension"
:
null
,
"current_weight"
:
null
,
"is_ffpe"
:
false
,
"tissue_type"
:
"Not Reported"
}
]
}
],
"file_name"
:
"c9478f7d-bfe3-4e80-8161-39b3d440fa16_wgs_gdc_realn.bam"
,
"mean_coverage"
:
5.452655
,
"proportion_reads_duplicated"
:
0.009253781617987946
,
"submitter_id"
:
"a4e380e5-420e-49af-986d-e721601065fb"
,
"data_category"
:
"Sequencing Reads"
,
"proportion_coverage_10x"
:
0.07674
,
"file_size"
:
42958286722
,
"contamination"
:
0
,
"average_base_quality"
:
32
,
"file_id"
:
"573ee7e9-b8bd-419e-808b-a027c4311731"
,
"data_type"
:
"Aligned Reads"
,
"average_insert_size"
:
207
,
"average_read_length"
:
51
,
"experimental_strategy"
:
"WGS"
,
"version"
:
"1"
,
"data_release"
:
"36.0 - 37.0"
},
"warnings"
:
{}
}
1.2.3 Request Parameters
- 41/232 -
© 2015-2024
Size and From
GDC API provides a pagination feature that limits the number of results returned by the API. It is implemented using size and
from query parameters.
The size query parameter specifies the maximum number of results to return. Default size is 10. If the number of query results
is greater than size , only some of the results will be returned.
The from query parameter specifies the first record to return out of the set of results. For example, if there are 20 cases returned
from the cases endpoint, then setting from to 11 will return results 12 to 20. The from parameter can be used in conjunction with
the size parameter to return a specific subset of results.
EXAMPLE
1.2.3 Request Parameters
- 42/232 -
© 2015-2024
Shell1 Python1 Response1 Shell2 Python2 Output2
curl
'https://api.gdc.cancer.gov/files?fields=file_name&from=0&size=2&pretty=true'
import
requests
import
json
files_endpt
=
'https://api.gdc.cancer.gov/files'
params
=
{
'fields'
:
'file_name'
,
'from'
:
0
,
'size'
:
2
}
response
=
requests
.
get
(
files_endpt
,
params
=
params
)
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
{
"data"
:
{
"hits"
:
[
{
"id"
:
"d570eccc-3c1c-4c4f-ae04-96be71fbe016"
,
"file_name"
:
"TCGA-AN-A0FL-01Z-00-DX1.20A041C6-A306-4599-A7D1-65032A252AA9.svs"
},
{
"id"
:
"0f8d8202-a1ca-4ea1-98b2-c20a6b08479a"
,
"file_name"
:
"nationwidechildrens.org_ssf.TCGA-AN-A0FL.xml"
}
],
"pagination"
:
{
"count"
:
2
,
"total"
:
931947
,
"size"
:
2
,
"from"
:
0
,
"sort"
:
""
,
"page"
:
1
,
"pages"
:
465974
}
},
"warnings"
:
{}
}
curl
'https://api.gdc.cancer.gov/files?fields=file_name&from=101&size=5&pretty=true'
import
requests
import
json
files_endpt
=
'https://api.gdc.cancer.gov/files'
params
=
{
'fields'
:
'file_name'
,
'from'
:
101
,
'size'
:
5
}
response
=
requests
.
get
(
files_endpt
,
params
=
params
)
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
{
"data"
:
{
"hits"
:
[
{
"id"
:
"297933f5-1316-4cb6-b53f-9dbfa7f3d7ed"
,
"file_name"
:
"TCGA-B6-A0RH-01A-02-TSB.ea83f31e-defb-4436-8a58-5b66b18d13b5.svs"
},
{
"id"
:
"2f31e897-b3e8-49f1-a400-ccf9f00f294a"
,
"file_name"
:
"URAEI_p_TCGASNP_b85_N_GenomeWideSNP_6_F01_735050.grch38.seg.v2.txt"
},
{
"id"
:
"ebd6cf90-4f6b-4193-887a-22fdb5645fbc"
,
"file_name"
:
"TCGA-BRCA.5994c06d-ee9b-4ead-b3d1-2e1f286f7d6d.ascat2.allelic_specific.seg.txt"
},
{
"id"
:
"aebd6b5a-e676-4357-93df-523b31b55ea0"
,
"file_name"
:
"TCGA-BRCA.c737131c-636f-4e1b-89b8-bb2d6ddd8164.star_fusion.rna_fusion.bedpe"
},
{
"id"
:
"aa83a7e7-e9cc-4330-a7be-ca750cffb74c"
,
"file_name"
:
"URAEI_p_TCGASNP_b85_N_GenomeWideSNP_6_F01_735050.birdseed.data.txt"
}
],
"pagination"
:
{
"count"
:
5
,
"total"
:
931947
,
"size"
:
5
,
"from"
:
101
,
"sort"
:
""
,
"page"
:
21
,
"pages"
:
186390
}
},
"warnings"
:
{}
}
1.2.3 Request Parameters
- 43/232 -
© 2015-2024
Sort
The sort query parameter sorts the results by a specific field, and with the sort direction specified using the :asc (ascending) or
:desc (descending) prefix, e.g. sort=field:desc . A list of all valid
field
names is available in Appendix A; the list can also be accessed
programmatically at the _mapping endpoint.
EXAMPLE
Sort cases by submitter_id in ascending order:
Shell Python Output
curl
'https://api.gdc.cancer.gov/cases?fields=submitter_id&sort=submitter_id:asc&pretty=true'
import
requests
import
json
cases_endpt
=
'https://api.gdc.cancer.gov/cases'
params
=
{
'fields'
:
'submitter_id'
,
'sort'
:
'submitter_id:asc'
}
response
=
requests
.
get
(
cases_endpt
,
params
=
params
)
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
{
"data"
:
{
"hits"
:
[
{
"id"
:
"be37f1f7-2f98-4f74-bc04-6dd2ae2afcad"
,
"submitter_id"
:
"01BR001"
},
{
"id"
:
"e6915db0-7c89-484d-8f9f-15cca68b82fc"
,
"submitter_id"
:
"01BR008"
},
{
"id"
:
"16614d46-172b-479c-992b-e80a8e9a2c59"
,
"submitter_id"
:
"01BR009"
},
{
"id"
:
"567fc9e3-17a6-42b1-a896-5e9a9507d1d8"
,
"submitter_id"
:
"01BR010"
},
{
"id"
:
"54e89878-a1bc-4f5a-9d68-4842a469586e"
,
"submitter_id"
:
"01BR015"
},
{
"id"
:
"a1c7b7b9-b8c8-48c3-9420-55497f9318fd"
,
"submitter_id"
:
"01BR017"
},
{
"id"
:
"ce3c8b98-e275-4cfd-a379-940d675a564b"
,
"submitter_id"
:
"01BR018"
},
{
"id"
:
"e4ce89ef-bcaa-418a-8a6b-3602793b9bbf"
,
"submitter_id"
:
"01BR020"
},
{
"id"
:
"19d3c861-8a5f-49a2-acc0-b55b25465c35"
,
"submitter_id"
:
"01BR023"
},
{
"id"
:
"afae8dce-294a-4108-bb28-376f804ae5c4"
,
"submitter_id"
:
"01BR025"
}
],
"pagination"
:
{
"count"
:
10
,
"total"
:
86962
,
"size"
:
10
,
"from"
:
0
,
"sort"
:
"None"
,
"page"
:
1
,
"pages"
:
8697
}
},
"warnings"
:
{}
}
1.2.3 Request Parameters
- 44/232 -
© 2015-2024
Facets
The facets parameter provides aggregate information for a specified field. It provides all values that exist for that field, and the
number of entities (cases, projects, files, or annotations) that this value. The primary intended use of this parameter is for
displaying aggregate information in the GDC Data Portal.
The facets parameter can be used in conjunction with the filters parameter to get aggregate information for a set of search
results. The following limitations apply when using facets and filters together:
1. The filters object's top level operator must be and , and the internal filters must be limited to: = , != , in , exclude , is , and not .
2. The information provided by facets for a given field will disregard any filters applied to that same field.
1.2.3 Request Parameters
- 45/232 -
© 2015-2024
EXAMPLE
This is an example of a request for a count of projects in each program.
1.2.3 Request Parameters
- 46/232 -
© 2015-2024
1.2.3 Request Parameters
- 47/232 -
© 2015-2024
Shell Python Response
curl
'https://api.gdc.cancer.gov/projects?facets=program.name&from=0&size=0&sort=program.name:asc&pretty=true'
import
requests
import
json
projects_endpt
=
'https://api.gdc.cancer.gov/projects'
params
=
{
'facets'
:
'program.name'
,
'from'
:
0
,
'size'
:
0
,
'sort'
:
'program.name:asc'
}
response
=
requests
.
get
(
projects_endpt
,
params
=
params
)
print
(
json
.
dumps
(
response
.
json
(),
indent
=
2
))
{
"data": {
"hits": [],
"aggregations": {
"program.name": {
"buckets": [
{
"doc_count": 33,
"key": "TCGA"
},
{
"doc_count": 10,
"key": "MATCH"
},
{
"doc_count": 9,
"key": "TARGET"
},
{
"doc_count": 4,
"key": "CGCI"
},
{
"doc_count": 3,
"key": "CMI"
},
{
"doc_count": 2,
"key": "BEATAML1.0"
},
{
"doc_count": 2,
"key": "CPTAC"
},
{
"doc_count": 2,
"key": "MP2PRT"
},
{
"doc_count": 1,
"key": "APOLLO"
},
{
"doc_count": 1,
"key": "CDDP_EAGLE"
},
{
"doc_count": 1,
"key": "CTSP"
},
{
"doc_count": 1,
"key": "EXCEPTIONAL_RESPONDERS"
},
{
"doc_count": 1,
"key": "FM"
},
{
"doc_count": 1,
"key": "HCMI"
},
{
"doc_count": 1,
"key": "MMRF"
},
{
"doc_count": 1,
"key": "NCICCR"
},
{
"doc_count": 1,
"key": "OHSU"
},
{
"doc_count": 1,
"key": "ORGANOID"
},
{
"doc_count": 1,
"key": "REBC"
},
{
"doc_count": 1,
"key": "TRIO"
},
{
"doc_count": 1,
"key": "VAREPOP"
1.2.3 Request Parameters
- 48/232 -
© 2015-2024
EXAMPLE
In this sample POST request, both filters and facets parameters are used. Note that facets ignores the primary_site filter.
1.2.3 Request Parameters
- 49/232 -
© 2015-2024
1.2.3 Request Parameters
- 50/232 -
© 2015-2024
Payload Shell Response
{
"filters"
:{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.project.primary_site"
,
"value"
:
"Kidney"
}
},
{
"op"
:
"="
,
"content"
:{
"field"
:
"project.program.name"
,
"value"
:
"TCGA"
}
}
]
},
"size"
:
"0"
,
"facets"
:
"project.primary_site"
,
"pretty"
:
"true"
}
curl
--request
POST
--header
"Content-Type: application/json"
--data
@Payload
'https://api.gdc.cancer.gov/v0/cases'
{
"data"
:
{
"hits"
:
[],
"aggregations"
:
{
"project.primary_site"
:
{
"buckets"
:
[
{
"doc_count"
:
1202
,
"key"
:
"kidney"
},
{
"doc_count"
:
1191
,
"key"
:
"brain"
},
{
"doc_count"
:
1176
,
"key"
:
"bronchus and lung"
},
{
"doc_count"
:
1156
,
"key"
:
"breast"
},
{
"doc_count"
:
952
,
"key"
:
"colon"
},
{
"doc_count"
:
947
,
"key"
:
"stomach"
},
{
"doc_count"
:
878
,
"key"
:
"uterus, nos"
},
{
"doc_count"
:
869
,
"key"
:
"ovary"
},
{
"doc_count"
:
821
,
"key"
:
"corpus uteri"
},
{
"doc_count"
:
789
,
"key"
:
"other and unspecified parts of tongue"
},
{
"doc_count"
:
670
,
"key"
:
"connective, subcutaneous and other soft tissues"
},
{
"doc_count"
:
633
,
"key"
:
"rectosigmoid junction"
},
{
"doc_count"
:
586
,
"key"
:
"bones, joints and articular cartilage of other and unspecified sites"
},
{
"doc_count"
:
565
,
"key"
:
"thyroid gland"
},
{
"doc_count"
:
528
,
"key"
:
"base of tongue"
},
{
"doc_count"
:
528
,
"key"
:
"floor of mouth"
},
{
"doc_count"
:
528
,
"key"
:
"gum"
},
1.2.3 Request Parameters
- 51/232 -
© 2015-2024
1.2.4 Alternative Request Format
The GDC API also supports POST requests with Content-Type: application/x-www-form-urlencoded (curl default), which require
payloads in the following format:
1.2.5 Using Wildcards
The GDC API supports the use of the wildcard character, an asterisk (*), in the value fields of a JSON query. For example, if a user
wanted to retrieve information about projects with a disease type that ended in "Adenocarcinoma" a query for "disease_type":
"*Adenocarcinoma" would be appropriate. See below:
1.2.6 Quicksearch Endpoint
The GDC Portal has a quicksearch functionality that allows for a project, case, or file to be queried from a search box. This function
calls the /v0/all endpoint, which retrieves the top cases, files, and projects that match to the query. The quicksearch can also be
used programmatically through the API. For example, a search term of 'TCGA' would produce the following query:
This endpoint can be used to quickly retrieve information about a file. For example, if a user wanted to know the UUID for
nationwidechildrens.org_biospecimen.TCGA-EL-A4K1.xml , the following query could be used to quickly retrieve it programmatically:
filters=%7B%0A%20%20%20%20%22op%22%3A%22in%22%2C%0A%20%20%20%20%22content%22%3A%7B%0A%20%20%20%20%20%20%20%20%22field%22%3A%22files.file_id%22%2C%0A%20%20%20%20%20%20%20%20%22value%22%3A%
d66fb59429bf%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22002c67f2-ff52-4246-9d65-a3f69df6789e%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22003143c8-bbbf-46b9-
a96f-f58530f4bb82%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%220043d981-3c6b-463f-b512-
ab1d076d3e62%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22004e2a2c-1acc-4873-9379-
ef1aa12283b6%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22005239a8-2e63-4ff1-9cd4-714f81837a61%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22006b8839-31e5-4697-
b912-8e3f4124dd15%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22006ce9a8-cf38-462e-
bb99-7f08499244ab%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22007ce9b5-3268-441e-9ffd-
b40d1127a319%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%220084a614-780b-42ec-b85f-7a1b83128cd3%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%2200a5e471-
a79f-4d56-8a4c-4847ac037400%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%2200ab2b5a-b59e-4ec9-
b297-76f74ff1d3fb%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%2200c5f14e-
a398-4076-95d1-25f320ee3a37%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%2200c74a8b-10aa-40cc-991e-3365ea1f3fce%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%2200df5a50-
bce3-4edf-
a078-641e54800dcb%22%0A%20%20%20%20%20%20%20%20%5D%0A%20%20%20%20%7D%0A%7D&fields=file_id,file_name,cases.submitter_id,cases.case_id,data_category,data_type,cases.samples.tumor_descriptor
{
"size":"20000",
"pretty":"TRUE",
"fields":"submitter_id,disease_type",
"format":"TSV",
"filters":{
"op":"=",
"content":{
"field":"disease_type",
"value":"*Adenocarcinoma"
}
}
}
Shell Response
curl
"https://api.gdc.cancer.gov/v0/all?query=TCGA&size=5"
{
"data"
:{
"query"
:{
"hits"
:[{
"disease_type"
:[
"Adenomas and Adenocarcinomas"
],
"id"
:
"UHJvamVjdDpUQ0dBLUFDQw=="
,
"name"
:
"Adrenocortical Carcinoma"
,
"primary_site"
:[
"Adrenal
gland"
],
"project_id"
:
"TCGA-ACC"
,
"project_quicksearch"
:
"Adrenocortical Carcinoma"
},{
"disease_type"
:[
"Adenomas and
Adenocarcinomas"
],
"id"
:
"UHJvamVjdDpUQ0dBLUtJQ0g="
,
"name"
:
"Kidney Chromophobe"
,
"primary_site"
:[
"Kidney"
],
"project_id"
:
"TCGA-KICH"
,
"project_quicksearch"
:
"Kidney
Chromophobe"
},{
"disease_type"
:[
"Adenomas and Adenocarcinomas"
],
"id"
:
"UHJvamVjdDpUQ0dBLUxJSEM="
,
"name"
:
"Liver Hepatocellular Carcinoma"
,
"primary_site"
:[
"Liver and
intrahepatic bile ducts"
],
"project_id"
:
"TCGA-LIHC"
,
"project_quicksearch"
:
"Liver Hepatocellular Carcinoma"
},{
"disease_type"
:[
"Myeloid
Leukemias"
],
"id"
:
"UHJvamVjdDpUQ0dBLUxBTUw="
,
"name"
:
"Acute Myeloid Leukemia"
,
"primary_site"
:[
"Hematopoietic and reticuloendothelial systems"
],
"project_id"
:
"TCGA-
LAML"
,
"project_quicksearch"
:
"Acute Myeloid Leukemia"
},{
"disease_type"
:[
"Adenomas and Adenocarcinomas"
],
"id"
:
"UHJvamVjdDpUQ0dBLUtJUlA="
,
"name"
:
"Kidney Renal Papillary
Cell Carcinoma"
,
"primary_site"
:[
"Kidney"
],
"project_id"
:
"TCGA-KIRP"
,
"project_quicksearch"
:
"Kidney Renal Papillary Cell Carcinoma"
}],
"total"
:
183550
}}}
Shell Response
curl
"https://api.gdc.cancer.gov/v0/all?query=nationwidechildrens.org_biospecimen.TCGA-EL-A4K1.xml&size=5"
{
"data"
:{
"query"
:{
"hits"
:[{
"file_id"
:
"a74abfec-db78-4ed4-9e4b-604b66e30e30"
,
"file_name"
:
"nationwidechildrens.org_biospecimen.TCGA-EL-
A4K1.xml"
,
"id"
:
"RmlsZTphNzRhYmZlYy1kYjc4LTRlZDQtOWU0Yi02MDRiNjZlMzBlMzA="
,
"submitter_id"
:
"nationwidechildrens.org_biospecimen.TCGA-EL-A4K1.xml"
}],
"total"
:
1
}}}
1.2.4 Alternative Request Format
- 52/232 -
© 2015-2024
1.2.7 Additional Examples
More examples of API functionality described in this section are provided in Additional Examples.
1.2.7 Additional Examples
- 53/232 -
© 2015-2024
1.3 Downloading Files
The GDC API implements file download functionality using data and manifest endpoints. The data endpoint allows users to
download files stored in the GDC by specifying file UUID(s). The manifest endpoint generates a download manifest file that can be
used with the GDC Data Transfer Tool to transfer large volumes of data.
Note: Downloading controlled access data requires the use of an authentication token. See Getting Started: Authentication for
details.
1.3.1 Data endpoint
To download a file, users can pass UUID(s) to the data endpoint. If a single UUID is provided, the API will return the associated
file. If a comma-separated list of UUIDs is provided, the API will return an archive file containing the requested files.
The data endpoint supports GET and POST requests as demonstrated in the following examples.
Downloading a Single File using GET
This example demonstrates downloading a single file from the GDC. Here we pass the file's UUID to the data endpoint with a GET
request.
Related Files
If the related_files=true parameter is specified, the following related files, if available, will be included in the download package
by the GDC API:
• BAM index files (BAI files)
• VCF index files (TBI files)
For example, this request will download a BAM file and its associated BAI file:
Shell Output
curl
--remote-name
--remote-header-name
'https://api.gdc.cancer.gov/data/5b2974ad-f932-499b-90a3-93577a9f0573'
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 6111k 100 6111k 0 0 414k 0 0:00:14 0:00:14 --:--:-- 412k
Shell Output
curl
--remote-name
--remote-header-name
-H
"x-auth-token:
$token
"
"https://api.gdc.cancer.gov/data/f587ef82-acbe-44f9-ad5a-6207e148f61f?related_files=true"
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 63.4M 0 63.4M 0 0 7541k 0 --:--:-- 0:00:08 --:--:-- 9.9M
1.3 Downloading Files
- 54/232 -
© 2015-2024
Downloading Multiple Files using GET
This example demonstrates downloading multiple files from the GDC using a GET request. The GDC API returns a .tar.gz archive
containing the downloaded files.
Note: This method supports downloading a limited number of files at one time. To download a large number of files, please use
POST.
DOWNLOADING AN UNCOMPRESSED GROUP OF FILES
If the ?tarfile parameter is specified to a data endpoint download query all files requested in the download string will be bundled
in a single tar file rather than a tar.gz file which is the default behavior.
Downloading Multiple Files using POST
The following two examples demonstrate downloading multiple files from the GDC using a POST request that contains a payload in
one of two formats: percent-encoded form data or JSON. The GDC API returns a .tar.gz archive containing the downloaded files.
POST REQUEST WITH FORM DATA PAYLOAD
POST requests that carry a payload of percent-encoded form data must include the HTTP header Content-Type: application/x-www-
form-urlencoded .
The payload is a string in the following format:
where UUID# corresponds to the UUIDs of the files to be downloaded.
In this example we use curl to download a set of files from the GDC Data Portal. The payload is stored in a plain text file named
Payload ; curl includes the Content-Type: application/x-www-form-urlencoded header by default.
POST REQUEST WITH JSON PAYLOAD
POST requests that carry a JSON payload must include the HTTP header Content-Type: application/json .
Shell Output
curl
--remote-name
--remote-header-name
'https://api.gdc.cancer.gov/data/e3228020-1c54-4521-9182-1ea14c5dc0f7,18e1e38e-0f0a-4a0e-918f-08e6201ea140'
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 287k 0 287k 0 0 30131 0 --:--:-- 0:00:09 --:--:-- 42759
Shell
curl
--remote-name
--remote-header-name
'https://api.gdc.cancer.gov/data/1da7105a-f0ff-479d-9f82-6c1d94456c91,77e73cc4-ff31-449e-8e3c-7ae5ce57838c?tarfile'
ids=UUID1&ids=UUID2&ids=UUID3...
Payload Shell Output
ids=59eb3fc5-9172-4828-8dec-0d9988073103&ids=869b7d7c-ff35-482a-aa8d-1a8675c161d3&ids=b8ffff40-aa0e-4534-
b05f-9311f16c2f6b&ids=51e14969-30a7-42d9-8168-4a5ea422ca4a&ids=adcfc856-990b-40fc-8f1e-67dfc2343fb7&ids=7f1e9aee-eb4e-4c79-8626-b603c9be124d&ids=62a8feb5-c660-4261-
bcd6-67fbb79bb422
curl
--remote-name
--remote-header-name
--request
POST
'https://api.gdc.cancer.gov/data'
--data
@Payload
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 6804k 0 6804k 100 286 245k 10 0:00:28 0:00:27 0:00:01 357k
1.3.1 Data endpoint
- 55/232 -
© 2015-2024
The payload is a string in the following format:
where UUID# corresponds to the UUIDs of the files to be downloaded.
In this example we use curl to download a set of files from the GDC Portal; the payload is stored in a plain text file named Payload .
Downloading Controlled-access Files
To download controlled-access files, a valid authentication token must be passed to the GDC API using the X-Auth-Token HTTP
header:
1.3.2 Manifest endpoint
The manifest endpoint generates a download manifest file that can be used with the GDC Data Transfer Tool. The Data Transfer
Tool is recommended for transferring large volumes of data. The GDC API can also generate a download manifest from a list of
results that match a Search and Retrieval query. To do this, append &return_type=manifest to the end of the query. Note that the
"size" parameter does not work with the manifest endpoint and will return the entire set of files.
{
"ids":[
"UUID1",
"UUID2",
...
"UUID3"
]
}
Payload Shell Output
{
"ids"
:[
"0451fc55-33ef-4151-a68c-cac59be716dc"
,
"0cc3d450-2c60-4cb0-a073-d92dc979fa5e"
,
"0de9bc40-3ef8-4fe7-b7d6-80a9339b0bf8"
,
"0f8d8202-a1ca-4ea1-98b2-c20a6b08479a"
]
}
curl
--remote-name
--remote-header-name
--request
POST
--header
'Content-Type: application/json'
--data
@request.txt
'https://api.gdc.cancer.gov/data'
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 5878k 0 5878k 100 205 290k 10 0:00:20 0:00:20 --:--:-- 198k
Shell Output
token
=
$(
<gdc-token-text-file.txt
)
curl
--remote-name
--remote-header-name
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/data/be6d269d-4305-4643-b98e-af703a067761'
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 65.8M 100 65.8M 0 0 271k 0 0:04:08 0:04:08 --:--:-- 288k
1.3.2 Manifest endpoint
- 56/232 -
© 2015-2024
Using the manifest endpoint
The manifest endpoint allows users to create a download manifest, which can be used with the GDC Data Transfer Tool to
download a large volume of data. The manifest endpoint generates a manifest file from a comma-separated list of UUIDs.
The manifest endpoint also supports HTTP POST requests in the same format as the data endpoint; see above for details.
Using return_type=manifest
Alternatively, users can create a manifest by appending &return_type=manifest to a Search and Retrieval query. In this example, we
generate a download manifest for RNA-seq data files from solid tissue normal samples, that are part of the TCGA-KIRC project:
Shell Output
curl
--remote-name
--remote-header-name
'https://api.gdc.cancer.gov/v0/manifest/a751cc7e-d2ff-4e9a-8645-09bf12612f1a,9c97e3fe-1610-4a92-9a24-ab3b9e4000e2'
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 274 100 274 0 0 1042 0 --:--:-- --:--:-- --:--:-- 1041
Shell Output
curl
--remote-name
--remote-header-name
'https://api.gdc.cancer.gov/files?
filters=%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22experimental_strategy%22%2C%22value%22%3A%5B%22RNA-
Seq%22%5D%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.project_id%22%2C%22value%22%3A%5B%22TCGA-
KIRC%22%5D%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.samples.sample_type%22%2C%22value%22%3A%5B%22Solid+Tissue+Normal%22%5D%7D%7D%5D%7D&return_type=manif
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 100k 0 100k 0 0 277k 0 --:--:-- --:--:-- --:--:-- 282k
1.3.2 Manifest endpoint
- 57/232 -
© 2015-2024
1.4 Data Analysis
The GDC data analysis endpoints allow API users to programmatically explore data in the GDC using advanced filters at a gene
and mutation level. Survival analysis data is also available.
1.4 Data Analysis
- 58/232 -
© 2015-2024
1.4.1 Endpoints
The following data analysis endpoints are available from the GDC API:
1.4.1 Endpoints
- 59/232 -
© 2015-2024
Node Endpoint Description
Genes /genes
Allows users to access summary information about each
gene using its Ensembl ID.
Gene
Expression
/gene_expression/availability
Allows users to retrieve the availability of gene expression
data for specific cases and/or genes.
/gene_expression/values
Get gene expression values for specified cases and genes.
/gene_expression/gene_selection
Select the most variably expressed genes for a collection
of cases and genes.
SSMS /ssms
Allows users to access information about each somatic
mutation. For example, a
ssm would represent the
transition of C to T at position 52000 of chromosome 1.
/ssms/ <ss m_id>
Get information about a specific ssm using a <ssm_id> ,
often supplemented with the expand option to show fields
of interest.
/ssm_occurrences
A
ssm entity as applied to a single instance (case). An
example of a ssm occurrence would be that the transition
of C to T at position 52000 of chromosome 1 occurred in
patient TCGA-XX-XXXX.
/ssm_occurrences/
<ssm_occurrences_id>
Get information about a specific ssm occurrence using a
<ssm_occurrences_id> , often supplemented with the expand
option to show fields of interest.
CNVS /cnvs
Allows users to access data about copy number variations
(cnvs). This data will be specifc to cnvs and not a specific
case.
/cnvs/ <cnv_id>
Get information about a specific copy number variation
using a <cnv_id> , often supplemented with the expand
option to show fields of interest.
/cnvs/ids
This endpoint will retrieve nodes that contain the queried
cnv_id. This is accomplished by adding the query
parameter: /cnvs/ids?query= <cnv_id> .
/cnv_occurrences
A cnv entity as applied to a single case.
/cnv_occurrences/ <cnv_occurrence_id>
Get information about a specific copy number variation
occurrence using a <cnv_occurrence_id> , often
supplemented with the expand option to show fields of
interest.
/cnv_occurrences/ids
This endpoint will retrieve nodes that contain the queried
cnv_occurrence_id. This is accomplished by adding the
query parameter: /cnv_occurrences/ids?
query= <cnv_occurrences_id>
Analysis /analysis/top_cases_counts_by_genes
Returns the number of cases with a mutation in each gene
listed in the gene_ids parameter for each project. Note
that this endpoint cannot be used with the format or
fields parameters.
/analysis/
top_mutated_genes_by_project
Returns a list of genes that have the most mutations
within a given project.
/analysis/top_mutated_cases_by_gene
Generates information about the cases that are most
affected by mutations in a given number of genes
1.4.1 Endpoints
- 60/232 -
© 2015-2024
The methods for retrieving information from these endpoints are very similar to those used for the cases and files endpoints.
These methods are explored in depth in the API Search and Retrieval documentation. The _mapping parameter can also be used
with each of these endpoints to generate a list of potential fields. For example:
https://api.gdc.cancer.gov/ssms/_mapping
While it is not an endpoint, the observation entity is featured in the visualization section of the API. The observation entity provides
information from the MAF file, such as read depth and normal genotype, that supports the validity of the associated ssm . An
example is demonstrated below:
Node Endpoint Description
/analysis/
mutated_cases_count_by_project
Returns counts for the number of cases that have
associated ssm data in each project. The number of
affected cases can be found under "case_with_ssm":
{"doc_count": $case_count}.
/analysis/survival
Survival plots can be generated in the Data Portal for
different subsets of data, based upon many query factors
such as variants, disease type and projects. This endpoint
can be used to programmatically retrieve the raw data to
generate these plots and apply different filters to the data.
(see Survival Example)
Shell Response
curl
"https://api.gdc.cancer.gov/ssms/57bb3f2e-ec05-52c2-ab02-7065b7d24849?expand=occurrence.case.observation.read_depth&pretty=true"
{
"data"
:
{
"ncbi_build"
:
"GRCh38"
,
"occurrence"
:
[
{
"case"
:
{
"observation"
:
[
{
"read_depth"
:
{
"t_ref_count"
:
321
,
"t_alt_count"
:
14
,
"t_depth"
:
335
,
"n_depth"
:
115
}
}
]
}
}
],
"tumor_allele"
:
"G"
,
"mutation_type"
:
"Simple Somatic Mutation"
,
"end_position"
:
14304578
,
"reference_allele"
:
"C"
,
"ssm_id"
:
"57bb3f2e-ec05-52c2-ab02-7065b7d24849"
,
"start_position"
:
14304578
,
"mutation_subtype"
:
"Single base substitution"
,
"cosmic_id"
:
null
,
"genomic_dna_change"
:
"chr5:g.14304578C>G"
,
"gene_aa_change"
:
[
"TRIO L229V"
,
"TRIO L437V"
,
"TRIO L447V"
,
"TRIO L496V"
],
"chromosome"
:
"chr5"
},
"warnings"
:
{}
}
1.4.1 Endpoints
- 61/232 -
© 2015-2024
1.4.2 Genes Endpoint Examples
Example 1: A user would like to access information about the gene ZMPSTE24 , which has an Ensembl gene ID of ENSG00000084073 .
This would be accomplished by appending ENSG00000084073 ( gene_id ) to the genes endpoint.
Example 2: A user wants a subset of elements such as a list of coordinates for all genes on chromosome 7. The query can be
filtered for only results from chromosome 7 using a JSON-formatted query that is URL-encoded.
Shell Response
curl
"https://api.gdc.cancer.gov/genes/ENSG00000084073?pretty=true"
{
"data"
:
{
"canonical_transcript_length"
:
3108
,
"description"
:
"This gene encodes a member of the peptidase M48A family. The encoded protein is a zinc metalloproteinase involved in the two step post-
translational proteolytic cleavage of carboxy terminal residues of farnesylated prelamin A to form mature lamin A. Mutations in this gene have been associated with
mandibuloacral dysplasia and restrictive dermopathy. [provided by RefSeq, Jul 2008]"
,
"cytoband"
:
[
"1p34.2"
],
"gene_start"
:
40258107
,
"canonical_transcript_length_genomic"
:
36078
,
"gene_id"
:
"ENSG00000084073"
,
"gene_strand"
:
1
,
"canonical_transcript_length_cds"
:
1425
,
"gene_chromosome"
:
"1"
,
"synonyms"
:
[
"FACE-1"
,
"HGPS"
,
"PRO1"
,
"STE24"
,
"Ste24p"
],
"is_cancer_gene_census"
:
null
,
"biotype"
:
"protein_coding"
,
"gene_end"
:
40294184
,
"canonical_transcript_id"
:
"ENST00000372759"
,
"symbol"
:
"ZMPSTE24"
,
"name"
:
"zinc metallopeptidase STE24"
},
"warnings"
:
{}
}
Shell Response
curl
"https://api.gdc.cancer.gov/genes?
pretty=true&fields=gene_id,symbol,gene_start,gene_end&format=tsv&size=2000&filters=%7B%0D%0A%22op%22%3A%22in%22%2C%0D%0A%22content%22%3A%7B%0D%0A%22field%22%3A%22gene_chromosome%22%2C%0D%
gene_start gene_end symbol id
28995231 29195451 CPVL ENSG00000106066
33014114 33062797 NT5C3A ENSG00000122643
143052320 143053347 OR6V1 ENSG00000225781
100400826 100428992 ZCWPW1 ENSG00000078487
73861159 73865893 WBSCR28 ENSG00000175877
64862999 64864370 EEF1DP4 ENSG00000213640
159231435 159233377 PIP5K1P2 ENSG00000229435
141972631 141973773 TAS2R38 ENSG00000257138
16646131 16706523 BZW2 ENSG00000136261
149239651 149255609 ZNF212 ENSG00000170260
57405025 57405090 MIR3147 ENSG00000266168
130393771 130442433 CEP41 ENSG00000106477
150800403 150805120 TMEM176A ENSG00000002933
93591573 93911265 GNGT1 ENSG00000127928
117465784 117715971 CFTR ENSG00000001626
5879827 5886362 OCM ENSG00000122543
144118461 144119360 OR2A15P ENSG00000239981
30424527 30478784 NOD1 ENSG00000106100
137227341 137343865 PTN ENSG00000105894
84876554 84876956 HMGN2P11 ENSG00000232605
107470018 107475659 GPR22 ENSG00000172209
31330711 31330896 RP11-463M14.1 ENSG00000271027
78017057 79453574 MAGI2 ENSG00000187391
55736779 55739605 CICP11 ENSG00000237799
142111749 142222324 RP11-1220K2.2 ENSG00000257743
(truncated)
1.4.2 Genes Endpoint Examples
- 62/232 -
© 2015-2024
1.4.3 Gene Expression Examples
Gene Expression Availability Endpoint
The purpose of this endpoint is to retrieve the availability of gene expression data for cases, genes, or both. The availability
response informs the user if gene expression data exists for each case or gene, which are specified with case and gene IDs. Gene
expression data is only available for protein-coding genes.
Example 1: A user wants to get the availability of gene expression data for a set of cases and genes.
Filter Shell Response
{
"case_ids"
:
[
"6d4f38db-a97b-4dc0-8dc5-2ac7f2cc5e38"
,
"e3b32485-b204-43a7-93a5-601408fcdf96"
],
"gene_ids"
:
[
"ENSG00000141510"
,
"ENSG00000181143"
]
}
curl
-
X
'POST'
\
'h
tt
ps
:
//api.gdc.cancer.gov/gene_expression/availability' \
-
H
'accep
t
:
applica
t
io
n
/jso
n
'
\
-
H
'Co
ntent
-
Type
:
applica
t
io
n
/jso
n
'
\
-
d
'
{
"case_ids"
:
[
"6d4f38db-a97b-4dc0-8dc5-2ac7f2cc5e38"
,
"e3b32485-b204-43a7-93a5-601408fcdf96"
],
"gene_ids"
:
[
"ENSG00000141510"
,
"ENSG00000181143"
]
}
'
{
"cases"
:
{
"details"
:
[
{
"case_id"
:
"6d4f38db-a97b-4dc0-8dc5-2ac7f2cc5e38"
,
"has_gene_expression_values"
:
false
},
{
"case_id"
:
"e3b32485-b204-43a7-93a5-601408fcdf96"
,
"has_gene_expression_values"
:
true
}
],
"with_gene_expression_count"
:
1
,
"without_gene_expression_count"
:
1
},
"genes"
:
{
"details"
:
[
{
"gene_id"
:
"ENSG00000141510"
,
"has_gene_expression_values"
:
true
},
{
"gene_id"
:
"ENSG00000181143"
,
"has_gene_expression_values"
:
true
}
],
"with_gene_expression_count"
:
2
,
"without_gene_expression_count"
:
0
}
}
1.4.3 Gene Expression Examples
- 63/232 -
© 2015-2024
Gene Expression Values Endpoint
The purpose of this endpoint is to retrieve the gene expression values for the given cases and genes. The response is a TSV
containing the expression values for genes to cases. The tsv_units of gene expression data must be defined by exactly one of the
following:
• uqfpkm - FPKM-UQ values. More information on calculations can be found here.
• median_centered_log2_uqfpkm - Median-centered log2(FPKM-UQ+1) values.
The median_centered_log2_uqfpkm is calculated through the following steps:
1. Calculate the Median: Determine the median of all provided log2(uqfpkm + 1) values.
2. Compute Median-Centered Values: Subtract the median from each log2(uqfpkm + 1) value.
3. Generate the Result Sequence: Create a new sequence with the median-centered values, preserving the original order.
Example 1: A user wants to get expression values using case IDs and gene IDs.
Gene Expression Gene Selection Endpoint
Select the most variably expressed genes for a collection of cases and collection of genes. The request must define a collection of
cases, a collection of genes, and a selection size. A minimum expression value may optionally be defined.
A collection of cases must be defined by case IDs.
A collection of genes must be defined by exactly one of the following:
•
gene_ids
• gene_type which has only one value: protein_coding .
Filter Shell Response
{
"case_ids"
:
[
"6d4f38db-a97b-4dc0-8dc5-2ac7f2cc5e38"
,
"e3b32485-b204-43a7-93a5-601408fcdf96"
,
"000ead0d-abf5-4606-be04-1ea31b999840"
,
"001ab32d-f924-4753-ad67-4366fb845ae6"
],
"gene_ids"
:
[
"ENSG00000141510"
,
"ENSG00000181143"
],
"tsv_units"
:
"median_centered_log2_uqfpkm"
,
"format"
:
"tsv"
}
curl
-X
'POST'
\
'https://api.gdc.cancer.gov/gene_expression/values'
\
-H
\
-H
'Content-Type: application/json'
\
-d
'{
"case_ids": [
"6d4f38db-a97b-4dc0-8dc5-2ac7f2cc5e38",
"e3b32485-b204-43a7-93a5-601408fcdf96",
"000ead0d-abf5-4606-be04-1ea31b999840",
"001ab32d-f924-4753-ad67-4366fb845ae6"
],
"gene_ids": [
"ENSG00000141510",
"ENSG00000181143"
],
"tsv_units": "median_centered_log2_uqfpkm",
"format": "tsv"
}'
gene_id 000ead0d-abf5-4606-be04-1ea31b999840 001ab32d-f924-4753-ad67-4366fb845ae6 e3b32485-b204-43a7-93a5-601408fcdf96
ENSG00000141510 -0.58248 1.75830 0.00000
ENSG00000181143 -0.02529 0.00000 3.52293
1.4.3 Gene Expression Examples
- 64/232 -
© 2015-2024
A selection size ( selection_size ) defines the maximum number of genes to select.
An optional threshold ( min_median_log2_uqfpkm ) defines a minimum value for expression. Defaults to 1 .
Example 1: A user wants to get the most variably expressed genes for a list of case UUIDs and a list of Ensembl gene IDs.
Filter Shell Response
{
"case_ids"
:
[
"000ead0d-abf5-4606-be04-1ea31b999840"
,
"001ab32d-f924-4753-ad67-4366fb845ae6"
,
"0024c94c-88ff-49d9-8dc4-bf77f832d85e"
,
"003f4f85-3244-4132-8c9d-c29f09382269"
,
"005d0639-c923-470f-a179-02a4dbb5cdf2"
,
"006931bb-f5b1-4aa4-b0a8-af517a912db0"
,
"0084e8b6-57fc-48b6-aa77-fec6e45161d2"
,
"008d3744-e7f0-41a5-a419-702960cf1ccb"
,
"0094e07c-1595-402e-9d38-68b9cac71e7b"
,
"00bd58bd-223d-433e-b60a-5bf355f342b1"
],
"gene_ids"
:
[
"ENSG00000141510"
,
"ENSG00000181143"
],
"selection_size"
:
1
}
curl
-X
'POST'
\
'https://api.gdc.cancer.gov/gene_expression/gene_selection'
\
-H
'accept: application/json'
\
-H
'Content-Type: application/json'
\
-d
'{
"case_ids": [
"000ead0d-abf5-4606-be04-1ea31b999840",
"001ab32d-f924-4753-ad67-4366fb845ae6",
"0024c94c-88ff-49d9-8dc4-bf77f832d85e",
"003f4f85-3244-4132-8c9d-c29f09382269",
"005d0639-c923-470f-a179-02a4dbb5cdf2",
"006931bb-f5b1-4aa4-b0a8-af517a912db0",
"0084e8b6-57fc-48b6-aa77-fec6e45161d2",
"008d3744-e7f0-41a5-a419-702960cf1ccb",
"0094e07c-1595-402e-9d38-68b9cac71e7b",
"00bd58bd-223d-433e-b60a-5bf355f342b1"
],
"gene_ids": [
"ENSG00000141510",
"ENSG00000181143"
],
"selection_size": 1
}'
{
"gene_selection"
:
[
{
"log2_uqfpkm_stddev"
:
0.9962971125913709
,
"log2_uqfpkm_median"
:
2.904457107848132
,
"gene_id"
:
"ENSG00000141510"
,
"symbol"
:
"TP53"
}
]
}
1.4.3 Gene Expression Examples
- 65/232 -
© 2015-2024
1.4.4 Simple Somatic Mutation Endpoint Examples
Example 1: Similar to the /genes endpoint, a user would like to retrieve information about the mutation based on its COSMIC ID.
This would be accomplished by creating a JSON filter, which will then be encoded to URL for the curl command.
Filter Shell Response
{
"op"
:
"in"
,
"content"
:{
"field"
:
"cosmic_id"
,
"value"
:[
"COSM1135366"
]
}
}
curl
'https://api.gdc.cancer.gov/ssms?
pretty=true&filters=%7B%0A%22op%22%3A%22in%22%2C%0A%22content%22%3A%7B%0A%22field%22%3A%22cosmic_id%22%2C%0A%2value%22%3A%5B%0A%22COSM1135366%22%0A%5D%0A%7D%0A%7D%0A'
{
"data"
:
{
"hits"
:
[
{
"id"
:
"edd1ae2c-3ca9-52bd-a124-b09ed304fcc2"
,
"start_position"
:
25245350
,
"gene_aa_change"
:
[
"KRAS G12D"
],
"reference_allele"
:
"C"
,
"ncbi_build"
:
"GRCh38"
,
"cosmic_id"
:
[
"COSM1135366"
,
"COSM521"
],
"mutation_subtype"
:
"Single base substitution"
,
"mutation_type"
:
"Simple Somatic Mutation"
,
"chromosome"
:
"chr12"
,
"ssm_id"
:
"edd1ae2c-3ca9-52bd-a124-b09ed304fcc2"
,
"genomic_dna_change"
:
"chr12:g.25245350C>T"
,
"tumor_allele"
:
"T"
,
"end_position"
:
25245350
}
],
"pagination"
:
{
"count"
:
1
,
"total"
:
1
,
"size"
:
10
,
"from"
:
0
,
"sort"
:
""
,
"page"
:
1
,
"pages"
:
1
}
},
"warnings"
:
{}
}
1.4.4 Simple Somatic Mutation Endpoint Examples
- 66/232 -
© 2015-2024
Example 2: Based on the previous example's ssm_id ( 8b3c1a7a-e4e0-5200-9d46-5767c2982145 ), a user would like to look at the
consequences and the VEP impact due to this ssm.
Shell JSON
curl
'https://api.gdc.cancer.gov/ssms/edd1ae2c-3ca9-52bd-a124-b09ed304fcc2?
pretty=true&expand=consequence.transcript&fields=consequence.transcript.annotation.vep_impact'
{
"data"
:
{
"consequence"
:
[
{
"transcript"
:
{
"annotation"
:
{
"vep_impact"
:
"MODERATE"
},
"transcript_id"
:
"ENST00000557334"
,
"aa_end"
:
12
,
"consequence_type"
:
"missense_variant"
,
"aa_start"
:
12
,
"is_canonical"
:
false
,
"aa_change"
:
"G12D"
,
"ref_seq_accession"
:
""
}
},
{
"transcript"
:
{
"annotation"
:
{
"vep_impact"
:
"MODERATE"
},
"transcript_id"
:
"ENST00000256078"
,
"aa_end"
:
12
,
"consequence_type"
:
"missense_variant"
,
"aa_start"
:
12
,
"is_canonical"
:
true
,
"aa_change"
:
"G12D"
,
"ref_seq_accession"
:
"NM_001369786.1&NM_033360.4"
}
},
{
"transcript"
:
{
"annotation"
:
{
"vep_impact"
:
"MODERATE"
},
"transcript_id"
:
"ENST00000311936"
,
"aa_end"
:
12
,
"consequence_type"
:
"missense_variant"
,
"aa_start"
:
12
,
"is_canonical"
:
false
,
"aa_change"
:
"G12D"
,
"ref_seq_accession"
:
"NM_001369787.1&NM_004985.5"
}
},
{
"transcript"
:
{
"annotation"
:
{
"vep_impact"
:
"MODERATE"
},
"transcript_id"
:
"ENST00000556131"
,
"aa_end"
:
12
,
"consequence_type"
:
"missense_variant"
,
"aa_start"
:
12
,
"is_canonical"
:
false
,
"aa_change"
:
"G12D"
,
"ref_seq_accession"
:
""
}
}
]
},
"warnings"
:
{}
}
1.4.4 Simple Somatic Mutation Endpoint Examples
- 67/232 -
© 2015-2024
1.4.5 Simple Somatic Mutation Occurrence Endpoint Examples
Example 1: A user wants to determine the chromosome in case TCGA-DU-6407 that contains the greatest number of ssms . As this
relates to mutations that are observed in a case, the ssm_occurrences endpoint is used.
Filter Shell Tsv
{
"op"
:
"in"
,
"content"
:{
"field"
:
"case.submitter_id"
,
"value"
:[
"TCGA-DU-6407"
]
}
}
curl
"https://api.gdc.cancer.gov/ssm_occurrences?
format=tsv&fields=ssm.chromosome&size=5000&filters=%7B%0D%0A%22op%22%3A%22in%22%2C%0D%0A%22content%22%3A%7B%0D%0A%22field%22%3A%22case.submitter_id%22%2C%0D%0A%22value%22%3A%5B%0D%0A%22TC
DU-6407%22%0D%0A%5D%0D%0A%7D%0D%0A%7D"
id ssm.chromosome
105e7811-4601-5ccb-ae93-e7107923599e chr16
faee73a9-4804-58ea-a91f-18c3d901774f chr2
99b3aad4-d368-506d-99d6-047cbe5dff0f chr2
2cb06277-993e-5502-b2c5-263037c45d18 chr10
f08dcc53-eadc-5ceb-bf31-f6b38629e4cb chr19
97c5b38b-fc96-57f5-8517-cc702b3aa70a chr6
19ca262d-b354-54a0-b582-c4719e37e91d chrX
b4822fc9-f0cc-56fd-9d97-f916234e309d chr2
22a07c7c-16ba-51df-a9a9-1e41e2a45225 chrX
0010a89d-9434-5d97-8672-36ee394767d0 chr17
3a023e72-da92-54f7-aa18-502c1076b2b0 chr5
391011ff-c1fd-5e2a-a128-652bc660f64c chr10
3548ecfe-5186-51e7-8f40-37f4654cd260 chr2
b67f31b5-0341-518e-8fcc-811cd2e36af1 chr3
4a93d7a5-988d-5055-80da-999dc3b45d80 chr1
9dc3f7cd-9efa-530a-8524-30d067e49d54 chr13
552c09d1-69b1-5c04-b543-524a6feae3eb chr3
dbc5eafa-ea26-5f1c-946c-b6974a345b69 chr12
d25129ad-3ad7-584f-bdeb-fba5c3881d32 chr17
1378cbc4-af88-55bb-b2e5-185bb4246d7a chr10
c44a93a1-5c73-5cff-b40e-98ce7e5fe57b chr19
1267330b-ae6d-5e25-b19e-34e98523679e chr21
1476a543-2951-5ec4-b165-67551b47d810 chr17
727c9d57-7b74-556f-aa5b-e1ca1f76d119 chr10
94abd5fd-d539-5a4a-8719-9615cf7cec5d chr1
a76469cb-973c-5d4d-bf82-7cf4e8f6c129 chr17
1.4.5 Simple Somatic Mutation Occurrence Endpoint Examples
- 68/232 -
© 2015-2024
Example 2: A user has retrieved a ssm_occurrence , and would like to determine if that case also has diagnostic information.
Shell Json
curl
'https://api.gdc.cancer.gov/ssm_occurrences/6fd8527d-5c40-5604-8fa9-0ce798eec231?pretty=true&expand=case.diagnoses'
{
"data"
:
{
"ssm_occurrence_id"
:
"6fd8527d-5c40-5604-8fa9-0ce798eec231"
,
"case"
:
{
"diagnoses"
:
[
{
"ajcc_pathologic_t"
:
"T3b"
,
"synchronous_malignancy"
:
"No"
,
"morphology"
:
"8720/3"
,
"ajcc_pathologic_stage"
:
"Stage IIB"
,
"ajcc_pathologic_n"
:
"N0"
,
"ajcc_pathologic_m"
:
"M0"
,
"submitter_id"
:
"TCGA-Z2-A8RT_diagnosis"
,
"days_to_diagnosis"
:
0
,
"last_known_disease_status"
:
"not reported"
,
"tissue_or_organ_of_origin"
:
"Skin, NOS"
,
"days_to_last_follow_up"
:
839.0
,
"age_at_diagnosis"
:
15342
,
"primary_diagnosis"
:
"Malignant melanoma, NOS"
,
"classification_of_tumor"
:
"not reported"
,
"prior_malignancy"
:
"no"
,
"year_of_diagnosis"
:
2012
,
"diagnosis_id"
:
"1d06a202-c51a-52e2-805f-eeb5f7fac14e"
,
"icd_10_code"
:
"C44.6"
,
"site_of_resection_or_biopsy"
:
"Skin of upper limb and shoulder"
,
"prior_treatment"
:
"No"
,
"state"
:
"released"
,
"tumor_grade"
:
"Not Reported"
,
"progression_or_recurrence"
:
"not reported"
,
"ajcc_staging_system_edition"
:
"7th"
}
]
}
},
"warnings"
:
{}
}
1.4.5 Simple Somatic Mutation Occurrence Endpoint Examples
- 69/232 -
© 2015-2024
1.4.6 Copy Number Variation Endpoint Examples
Example 1: A user is interested in finding the first 30 cnvs found on chromosome 4 that have a cnv loss.
Filter Shell Tsv
{
"op"
:
"and"
,
"content"
:
[
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"chromosome"
,
"value"
:
[
"4"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"cnv_change"
,
"value"
:
[
"Loss"
]
}
}
]
}
curl
'https://api.gdc.cancer.gov/cnvs?filters=%7B%0D%0A+++%22op%22%3A+%22and%22%2C%0D%0A++++%22content%22%3A+%5B%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+
%22in%22%2C%0D%0A++++++++++++%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22chromosome%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A++++++++++++++
++++++%224%22%0D%0A++++++++++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%2C%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+%22in%22%2C%0D%0A++++++++++++
%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22cnv_change%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A++++++++++++++++++++%22Loss%22%0D%0A+++++++
+++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%0D%0A++++%5D%0D%0A%7D&size=30&sort=start_position&format=tsv'
chromosome cnv_change cnv_id end_position gene_level_cn id ncbi_build start_position
4 Loss 11381600-f064-5c42-90d2-a5c79c8b23e1 88208 True 11381600-f064-5c42-90d2-a5c79c8b23e1 GRCh38 53286
4 Loss edef0f2f-c1a7-507c-842f-e1f8a568df9d 202303 True edef0f2f-c1a7-507c-842f-e1f8a568df9d GRCh38 124501
4 Loss eba92f9a-b045-54a8-948a-451e439ed418 305474 True eba92f9a-b045-54a8-948a-451e439ed418 GRCh38 270675
4 Loss 89319453-2a3f-5ebe-be30-8af0426e0343 384868 True 89319453-2a3f-5ebe-be30-8af0426e0343 GRCh38 337814
4 Loss 6567929c-4b6f-582b-aedf-acde2c0ec736 499156 True 6567929c-4b6f-582b-aedf-acde2c0ec736 GRCh38 425815
4 Loss 2daff58b-5065-50cd-8239-253180eaee81 540200 True 2daff58b-5065-50cd-8239-253180eaee81 GRCh38 499210
4 Loss 2b42c8d4-6d85-5352-96e1-9e52e722c248 576295 True 2b42c8d4-6d85-5352-96e1-9e52e722c248 GRCh38 573880
4 Loss 2646cdc7-7602-59a4-ae4f-d171352bae88 670782 True 2646cdc7-7602-59a4-ae4f-d171352bae88 GRCh38 625573
4 Loss c11ad392-949f-593f-a3ab-d834b2f82809 674330 True c11ad392-949f-593f-a3ab-d834b2f82809 GRCh38 672436
4 Loss f31be658-4de0-549e-81be-e79759879acf 682033 True f31be658-4de0-549e-81be-e79759879acf GRCh38 673580
4 Loss d72c62f2-fc29-5b83-9839-7f6b03970aff 689271 True d72c62f2-fc29-5b83-9839-7f6b03970aff GRCh38 681829
4 Loss 45448d47-6e13-5d30-824d-96150a7f55c6 770640 True 45448d47-6e13-5d30-824d-96150a7f55c6 GRCh38 705748
4 Loss 517e65ea-9084-54c2-abe0-b1b47e9f872c 826129 True 517e65ea-9084-54c2-abe0-b1b47e9f872c GRCh38 784957
4 Loss b5a09c9b-d842-5b76-a500-56f18252c29d 932373 True b5a09c9b-d842-5b76-a500-56f18252c29d GRCh38 849276
4 Loss e3a3b61d-2881-5ad4-90bf-58ef29ae9ecb 958656 True e3a3b61d-2881-5ad4-90bf-58ef29ae9ecb GRCh38 932387
4 Loss 8630a1b6-3215-5b71-903a-ad9845505afc 986895 True 8630a1b6-3215-5b71-903a-ad9845505afc GRCh38 958887
4 Loss f748b06f-1fb7-53a9-a7d6-2c22a3ae6de5 993440 True f748b06f-1fb7-53a9-a7d6-2c22a3ae6de5 GRCh38 979073
4 Loss a5e4a63f-c5f6-5f0f-a6b6-f51bfb643533 1004564 True a5e4a63f-c5f6-5f0f-a6b6-f51bfb643533 GRCh38 986997
4 Loss 73f6fbbe-6fd9-524c-a7c8-a7cf3f08ada4 1026898 True 73f6fbbe-6fd9-524c-a7c8-a7cf3f08ada4 GRCh38 1009936
4 Loss adad579a-b002-5022-823a-570c59549065 1113564 True adad579a-b002-5022-823a-570c59549065 GRCh38 1056250
4 Loss d5a5c45e-594b-5cbc-97d5-75fc5155d021 1208962 True d5a5c45e-594b-5cbc-97d5-75fc5155d021 GRCh38 1166932
4 Loss 6c910993-faa8-5abc-b433-b3afcc5e9e11 1249953 True 6c910993-faa8-5abc-b433-b3afcc5e9e11 GRCh38 1211445
4 Loss 4453b4cb-7d8a-5e26-a856-eac62eec287a 1340147 True 4453b4cb-7d8a-5e26-a856-eac62eec287a GRCh38 1289887
4 Loss 6db1001a-a41b-518d-9491-2bf41544d90f 1395989 True 6db1001a-a41b-518d-9491-2bf41544d90f GRCh38 1345691
4 Loss 6bef981a-ead1-5aa7-8a69-8d38e576e5c0 1406442 True 6bef981a-ead1-5aa7-8a69-8d38e576e5c0 GRCh38 1402932
4 Loss af6e0b49-922a-587e-b353-4b9414605cf1 1684261 True af6e0b49-922a-587e-b353-4b9414605cf1 GRCh38 1617915
4 Loss 400352ad-8526-562a-bbf4-29b90a48f46f 1712344 True 400352ad-8526-562a-bbf4-29b90a48f46f GRCh38 1692731
4 Loss 8811414d-2434-56c6-afe5-a998c9b18d47 1745171 True 8811414d-2434-56c6-afe5-a998c9b18d47 GRCh38 1712891
4 Loss 169c4409-0256-5841-9314-f1a4dd2bcc38 1721358 True 169c4409-0256-5841-9314-f1a4dd2bcc38 GRCh38 1715952
4 Loss 1712ccac-6e70-5fb3-b71e-1a029eaf047c 1808872 True 1712ccac-6e70-5fb3-b71e-1a029eaf047c GRCh38 1793293
1.4.6 Copy Number Variation Endpoint Examples
- 70/232 -
© 2015-2024
Example 2: A user wants to determine the location and identity of the gene affected by the cnv
544c4896-0152-5787-8d77-894a16f0ded0 , and determine whether the gene is found within the Cancer Gene Census.
1.4.7 Copy Number Variation Occurrence Enpoint Examples
Example 1: A user is interested in finding cases that have both cnv and ssm data for females diagnosed with Squamous Cell
Neoplasms and have a cnv gain change on chromosome 9. It is important to note that for a case like this, where multiple
Shell Json
curl
'https://api.gdc.cancer.gov/cnvs/544c4896-0152-5787-8d77-894a16f0ded0?pretty=true&expand=consequence.gene'
{
"data"
:
{
"start_position"
:
27100354
,
"consequence"
:
[
{
"gene"
:
{
"biotype"
:
"protein_coding"
,
"symbol"
:
"HOXA2"
,
"gene_id"
:
"ENSG00000105996"
}
}
],
"gene_level_cn"
:
true
,
"cnv_change"
:
"Gain"
,
"ncbi_build"
:
"GRCh38"
,
"chromosome"
:
"7"
,
"cnv_id"
:
"544c4896-0152-5787-8d77-894a16f0ded0"
,
"end_position"
:
27102686
},
"warnings"
:
{}
}
1.4.7 Copy Number Variation Occurrence Enpoint Examples
- 71/232 -
© 2015-2024
arguments are need for one filtered field, it is easier for the API to have multiple filters for the same field,
case.available_variation_data in this example, than having one filter with multiple arguments.
1.4.7 Copy Number Variation Occurrence Enpoint Examples
- 72/232 -
© 2015-2024
Filter Shell Tsv
{
"op"
:
"and"
,
"content"
:
[
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"cnv.cnv_change"
,
"value"
:
[
"Gain"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"case.demographic.gender"
,
"value"
:
[
"female"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"case.available_variation_data"
,
"value"
:
[
"cnv"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"case.available_variation_data"
,
"value"
:
[
"ssm"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"cnv.chromosome"
,
"value"
:
[
"9"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"case.disease_type"
,
"value"
:
[
"Squamous Cell Neoplasms"
]
}
}
]
}
curl
'https://api.gdc.cancer.gov/cnv_occurrences?filters=%7B%0D%0A++++%22op%22%3A+%22and%22%2C%0D%0A++++%22content%22%3A+%5B%0D%0A++++++++%7B%0D%0A++++++++++++
%22op%22%3A+%22in%22%2C%0D%0A++++++++++++%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22cnv.cnv_change%22%2C%0D%0A++++++++++++++++%22value%22%3A+
%5B%0D%0A++++++++++++++++++++%22Gain%22%0D%0A++++++++++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%2C%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+
%22in%22%2C%0D%0A++++++++++++%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22case.demographic.gender%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A+
+++++++++++++++++++%22female%22%0D%0A++++++++++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%2C%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+%22in%22%2C%0D%0A++++
++++++++%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22case.available_variation_data%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A++++++++++++++++
++++%22cnv%22%0D%0A++++++++++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%2C%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+%22in%22%2C%0D%0A++++++++++++
%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22case.available_variation_data%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A++++++++++++++++++++
%22ssm%22%0D%0A++++++++++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%2C%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+%22in%22%2C%0D%0A++++++++++++
%22content%22%3A+%7B%0D%0A++++++++++++++++%22field%22%3A+%22cnv.chromosome%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A++++++++++++++++++++%229%22%0D%0A++++++
++++++++++%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%2C%0D%0A++++++++%7B%0D%0A++++++++++++%22op%22%3A+%22in%22%2C%0D%0A++++++++++++%22content%22%3A+%7B%0D%0A+++++++++
+++++++%22field%22%3A+%22case.disease_type%22%2C%0D%0A++++++++++++++++%22value%22%3A+%5B%0D%0A++++++++++++++++++++%22Squamous+Cell+Neoplasms%22%0D%0A++++++++++++++++
%5D%0D%0A++++++++++++%7D%0D%0A++++++++%7D%0D%0A++++%5D%0D%0A%7D&fields=case.available_variation_data,case.case_id&format=tsv'
case.available_variation_data.0 case.available_variation_data.1 case.case_id id
cnv ssm da30a845-c4d3-4c78-b8b0-210239224f8f 3caf6e3b-024f-57b6-bdd9-3b67e423cc11
cnv ssm 0809ba8b-4ab6-4f43-934c-c1ccbc014a7e e6afe58e-c99c-5c8d-920e-8ba4daad4d89
cnv ssm 8e0e456e-85ee-4de5-8f0b-72393d6acde0 9d983d9c-8320-53f1-9054-e46926c5b834
cnv ssm 64a195f6-2212-4e81-bccc-e39c77a10908 8caeaecc-ad68-539d-8b3c-8320b3684763
cnv ssm 2f6a0e87-1e6c-41f3-93e0-3e505fa654b0 4862c166-0f37-5e3c-ae4e-a2964de01cea
cnv ssm f0daf315-8909-4cda-886d-a2770b08db94 099ff6cd-bd28-56f4-a181-6b02f3ba7503
cnv ssm ff3808e4-eece-4046-819b-fe1019317f8e 0c936aa2-393e-5463-a431-3613b4510021
cnv ssm 9205dc07-93f5-4b5e-924e-8e097616160f 133d27a7-fdc6-5082-a1f3-022b89f4e851
cnv ssm 79ae5209-f476-4d65-a6c0-ebc18d7c8942 7a5e6bb1-8af3-5964-a3cc-c53602c8b099
cnv ssm ff7099e1-8ff9-48e4-842d-46e98076e7e6 fb27fa8f-aa31-5e20-84da-8f45bb675405
1.4.7 Copy Number Variation Occurrence Enpoint Examples
- 73/232 -
© 2015-2024
Example 2: A user is interested in the first cnv occurrence ( 3b9f7ecc-2280-5b89-80f9-ec8d6c5e604e ) from the previous example, and
would like to know more about the case exposures and demographics.
1.4.8 Analysis Endpoints
In addition to the ssms , ssm_occurrences , and genes endpoints mentioned previously, several /analysis endpoints were designed to
quickly retrieve specific datasets used for visualization display.
Example 1: The /analysis/top_cases_counts_by_genes endpoint gives the number of cases with a mutation in each gene listed in the
gene_ids parameter for each project. Note that this endpoint cannot be used with the format or fields parameters. In this
instance, the query will produce the number of cases in each projects with mutations in the gene ENSG00000155657 .
This JSON-formatted output is broken up by project. For an example, see the following text:
Shell Json
curl
'https://api.gdc.cancer.gov/cnv_occurrences/3b9f7ecc-2280-5b89-80f9-ec8d6c5e604e?pretty=true&expand=cnv,case,case.exposures,case.demographic'
{
"data"
:
{
"cnv"
:
{
"start_position"
:
68815994
,
"gene_level_cn"
:
true
,
"cnv_change"
:
"Gain"
,
"ncbi_build"
:
"GRCh38"
,
"chromosome"
:
"4"
,
"variant_status"
:
"Tumor Only"
,
"cnv_id"
:
"1a889109-30d5-51e3-848f-9f615c69f407"
,
"end_position"
:
68832023
},
"cnv_occurrence_id"
:
"3b9f7ecc-2280-5b89-80f9-ec8d6c5e604e"
,
"case"
:
{
"exposures"
:
[
{
"cigarettes_per_day"
:
5.47945205479452
,
"alcohol_history"
:
"Not Reported"
,
"exposure_id"
:
"f7b08a8e-d22b-5cb0-be9f-b922c9ca87d2"
,
"submitter_id"
:
"TCGA-38-4629_exposure"
,
"state"
:
"released"
,
"pack_years_smoked"
:
100.0
}
],
"primary_site"
:
"Bronchus and lung"
,
"disease_type"
:
"Adenomas and Adenocarcinomas"
,
"available_variation_data"
:
[
"cnv"
,
"ssm"
],
"case_id"
:
"127bf818-f7e5-46b5-a9de-39f6d96b8b83"
,
"submitter_id"
:
"TCGA-38-4629"
,
"state"
:
"released"
,
"demographic"
:
{
"demographic_id"
:
"9ea1f795-9510-5acc-a9a5-bf1379e6635a"
,
"ethnicity"
:
"not hispanic or latino"
,
"gender"
:
"male"
,
"race"
:
"white"
,
"vital_status"
:
"Dead"
,
"age_at_index"
:
68
,
"submitter_id"
:
"TCGA-38-4629_demographic"
,
"days_to_death"
:
864
,
"days_to_birth"
:
-25104
,
"state"
:
"released"
,
"year_of_death"
:
2005
,
"year_of_birth"
:
1935
}
}
},
"warnings"
:
{}
}
curl
"https://api.gdc.cancer.gov/analysis/top_cases_counts_by_genes?gene_ids=ENSG00000155657&pretty=true"
$
curl
"https://api.gdc.cancer.gov/analysis/top_cases_counts_by_genes?gene_ids=ENSG00000155657&pretty=true"
{
"took"
:
6
,
"timed_out"
:
false
,
"_shards"
:
{
"total"
:
12
,
"successful"
:
12
,
1.4.8 Analysis Endpoints
- 74/232 -
© 2015-2024
"skipped"
:
0
,
"failed"
:
0
},
"hits"
:
{
"total"
:
{
"value"
:
5967
,
"relation"
:
"eq"
},
"max_score"
:
null
,
"hits"
:
[]
},
"aggregations"
:
{
"projects"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"TCGA-BRCA"
,
"doc_count"
:
425
,
"genes"
:
{
"doc_count"
:
4031450
,
"my_genes"
:
{
"doc_count"
:
425
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
425
}
]
}
}
}
},
{
"key"
:
"TCGA-LUSC"
,
"doc_count"
:
423
,
"genes"
:
{
"doc_count"
:
4123089
,
"my_genes"
:
{
"doc_count"
:
423
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
423
}
]
}
}
}
},
{
"key"
:
"CPTAC-3"
,
"doc_count"
:
421
,
"genes"
:
{
"doc_count"
:
251552
,
"my_genes"
:
{
"doc_count"
:
421
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
421
}
]
}
}
}
},
{
"key"
:
"TCGA-SKCM"
,
"doc_count"
:
391
,
"genes"
:
{
"doc_count"
:
3040929
,
"my_genes"
:
{
"doc_count"
:
391
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
391
}
]
}
}
1.4.8 Analysis Endpoints
- 75/232 -
© 2015-2024
}
},
{
"key"
:
"TCGA-LUAD"
,
"doc_count"
:
345
,
"genes"
:
{
"doc_count"
:
3188761
,
"my_genes"
:
{
"doc_count"
:
345
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
345
}
]
}
}
}
},
{
"key"
:
"TCGA-OV"
,
"doc_count"
:
341
,
"genes"
:
{
"doc_count"
:
3728561
,
"my_genes"
:
{
"doc_count"
:
341
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
341
}
]
}
}
}
},
{
"key"
:
"TCGA-STAD"
,
"doc_count"
:
300
,
"genes"
:
{
"doc_count"
:
2145783
,
"my_genes"
:
{
"doc_count"
:
300
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
300
}
]
}
}
}
},
{
"key"
:
"TCGA-UCEC"
,
"doc_count"
:
297
,
"genes"
:
{
"doc_count"
:
1637055
,
"my_genes"
:
{
"doc_count"
:
297
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
297
}
]
}
}
}
},
{
"key"
:
"TCGA-HNSC"
,
"doc_count"
:
293
,
"genes"
:
{
"doc_count"
:
2325617
,
"my_genes"
:
{
"doc_count"
:
293
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
1.4.8 Analysis Endpoints
- 76/232 -
© 2015-2024
"key"
:
"ENSG00000155657"
,
"doc_count"
:
293
}
]
}
}
}
},
{
"key"
:
"TCGA-COAD"
,
"doc_count"
:
288
,
"genes"
:
{
"doc_count"
:
1695280
,
"my_genes"
:
{
"doc_count"
:
288
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
288
}
]
}
}
}
},
{
"key"
:
"TCGA-BLCA"
,
"doc_count"
:
280
,
"genes"
:
{
"doc_count"
:
2466835
,
"my_genes"
:
{
"doc_count"
:
280
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
280
}
]
}
}
}
},
{
"key"
:
"MMRF-COMMPASS"
,
"doc_count"
:
181
,
"genes"
:
{
"doc_count"
:
45977
,
"my_genes"
:
{
"doc_count"
:
181
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
181
}
]
}
}
}
},
{
"key"
:
"TCGA-LIHC"
,
"doc_count"
:
167
,
"genes"
:
{
"doc_count"
:
1216775
,
"my_genes"
:
{
"doc_count"
:
167
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
167
}
]
}
}
}
},
{
"key"
:
"TCGA-CESC"
,
"doc_count"
:
161
,
"genes"
:
{
"doc_count"
:
1103281
,
"my_genes"
:
{
1.4.8 Analysis Endpoints
- 77/232 -
© 2015-2024
"doc_count"
:
161
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
161
}
]
}
}
}
},
{
"key"
:
"TCGA-KIRC"
,
"doc_count"
:
161
,
"genes"
:
{
"doc_count"
:
842546
,
"my_genes"
:
{
"doc_count"
:
161
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
161
}
]
}
}
}
},
{
"key"
:
"CPTAC-2"
,
"doc_count"
:
131
,
"genes"
:
{
"doc_count"
:
72575
,
"my_genes"
:
{
"doc_count"
:
131
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
131
}
]
}
}
}
},
{
"key"
:
"TCGA-GBM"
,
"doc_count"
:
131
,
"genes"
:
{
"doc_count"
:
756809
,
"my_genes"
:
{
"doc_count"
:
131
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
131
}
]
}
}
}
},
{
"key"
:
"TCGA-ESCA"
,
"doc_count"
:
129
,
"genes"
:
{
"doc_count"
:
1210888
,
"my_genes"
:
{
"doc_count"
:
129
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
129
}
]
}
}
}
},
1.4.8 Analysis Endpoints
- 78/232 -
© 2015-2024
{
"key"
:
"TCGA-PRAD"
,
"doc_count"
:
101
,
"genes"
:
{
"doc_count"
:
379949
,
"my_genes"
:
{
"doc_count"
:
101
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
101
}
]
}
}
}
},
{
"key"
:
"HCMI-CMDC"
,
"doc_count"
:
99
,
"genes"
:
{
"doc_count"
:
54829
,
"my_genes"
:
{
"doc_count"
:
99
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
99
}
]
}
}
}
},
{
"key"
:
"TCGA-READ"
,
"doc_count"
:
98
,
"genes"
:
{
"doc_count"
:
726313
,
"my_genes"
:
{
"doc_count"
:
98
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
98
}
]
}
}
}
},
{
"key"
:
"TCGA-LGG"
,
"doc_count"
:
95
,
"genes"
:
{
"doc_count"
:
424689
,
"my_genes"
:
{
"doc_count"
:
95
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
95
}
]
}
}
}
},
{
"key"
:
"TCGA-KIRP"
,
"doc_count"
:
93
,
"genes"
:
{
"doc_count"
:
521936
,
"my_genes"
:
{
"doc_count"
:
93
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
93
1.4.8 Analysis Endpoints
- 79/232 -
© 2015-2024
}
]
}
}
}
},
{
"key"
:
"TCGA-SARC"
,
"doc_count"
:
93
,
"genes"
:
{
"doc_count"
:
903111
,
"my_genes"
:
{
"doc_count"
:
93
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
93
}
]
}
}
}
},
{
"key"
:
"TCGA-TGCT"
,
"doc_count"
:
51
,
"genes"
:
{
"doc_count"
:
524456
,
"my_genes"
:
{
"doc_count"
:
51
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
51
}
]
}
}
}
},
{
"key"
:
"TARGET-ALL-P2"
,
"doc_count"
:
50
,
"genes"
:
{
"doc_count"
:
1882
,
"my_genes"
:
{
"doc_count"
:
50
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
50
}
]
}
}
}
},
{
"key"
:
"TCGA-KICH"
,
"doc_count"
:
43
,
"genes"
:
{
"doc_count"
:
353674
,
"my_genes"
:
{
"doc_count"
:
43
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
43
}
]
}
}
}
},
{
"key"
:
"TCGA-PAAD"
,
"doc_count"
:
43
,
"genes"
:
{
"doc_count"
:
300427
,
"my_genes"
:
{
"doc_count"
:
43
,
"gene_id"
:
{
1.4.8 Analysis Endpoints
- 80/232 -
© 2015-2024
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
43
}
]
}
}
}
},
{
"key"
:
"CGCI-HTMCP-CC"
,
"doc_count"
:
37
,
"genes"
:
{
"doc_count"
:
3606
,
"my_genes"
:
{
"doc_count"
:
37
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
37
}
]
}
}
}
},
{
"key"
:
"CDDP_EAGLE-1"
,
"doc_count"
:
32
,
"genes"
:
{
"doc_count"
:
16980
,
"my_genes"
:
{
"doc_count"
:
32
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
32
}
]
}
}
}
},
{
"key"
:
"TCGA-ACC"
,
"doc_count"
:
29
,
"genes"
:
{
"doc_count"
:
283969
,
"my_genes"
:
{
"doc_count"
:
29
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
29
}
]
}
}
}
},
{
"key"
:
"CMI-MBC"
,
"doc_count"
:
28
,
"genes"
:
{
"doc_count"
:
3581
,
"my_genes"
:
{
"doc_count"
:
28
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
28
}
]
}
}
}
},
{
"key"
:
"TCGA-THCA"
,
1.4.8 Analysis Endpoints
- 81/232 -
© 2015-2024
"doc_count"
:
28
,
"genes"
:
{
"doc_count"
:
89120
,
"my_genes"
:
{
"doc_count"
:
28
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
28
}
]
}
}
}
},
{
"key"
:
"TCGA-UCS"
,
"doc_count"
:
28
,
"genes"
:
{
"doc_count"
:
283673
,
"my_genes"
:
{
"doc_count"
:
28
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
28
}
]
}
}
}
},
{
"key"
:
"TCGA-MESO"
,
"doc_count"
:
21
,
"genes"
:
{
"doc_count"
:
137002
,
"my_genes"
:
{
"doc_count"
:
21
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
21
}
]
}
}
}
},
{
"key"
:
"TCGA-PCPG"
,
"doc_count"
:
19
,
"genes"
:
{
"doc_count"
:
99444
,
"my_genes"
:
{
"doc_count"
:
19
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
19
}
]
}
}
}
},
{
"key"
:
"TARGET-NBL"
,
"doc_count"
:
15
,
"genes"
:
{
"doc_count"
:
829
,
"my_genes"
:
{
"doc_count"
:
15
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
15
}
]
1.4.8 Analysis Endpoints
- 82/232 -
© 2015-2024
}
}
}
},
{
"key"
:
"TCGA-UVM"
,
"doc_count"
:
12
,
"genes"
:
{
"doc_count"
:
68201
,
"my_genes"
:
{
"doc_count"
:
12
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
12
}
]
}
}
}
},
{
"key"
:
"EXCEPTIONAL_RESPONDERS-ER"
,
"doc_count"
:
11
,
"genes"
:
{
"doc_count"
:
10617
,
"my_genes"
:
{
"doc_count"
:
11
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
11
}
]
}
}
}
},
{
"key"
:
"TCGA-THYM"
,
"doc_count"
:
11
,
"genes"
:
{
"doc_count"
:
59647
,
"my_genes"
:
{
"doc_count"
:
11
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
11
}
]
}
}
}
},
{
"key"
:
"BEATAML1.0-COHORT"
,
"doc_count"
:
10
,
"genes"
:
{
"doc_count"
:
279
,
"my_genes"
:
{
"doc_count"
:
10
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
10
}
]
}
}
}
},
{
"key"
:
"TARGET-OS"
,
"doc_count"
:
10
,
"genes"
:
{
"doc_count"
:
414
,
"my_genes"
:
{
"doc_count"
:
10
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
1.4.8 Analysis Endpoints
- 83/232 -
© 2015-2024
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
10
}
]
}
}
}
},
{
"key"
:
"TCGA-LAML"
,
"doc_count"
:
10
,
"genes"
:
{
"doc_count"
:
10175
,
"my_genes"
:
{
"doc_count"
:
10
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
10
}
]
}
}
}
},
{
"key"
:
"TCGA-DLBC"
,
"doc_count"
:
9
,
"genes"
:
{
"doc_count"
:
63497
,
"my_genes"
:
{
"doc_count"
:
9
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
9
}
]
}
}
}
},
{
"key"
:
"TCGA-CHOL"
,
"doc_count"
:
8
,
"genes"
:
{
"doc_count"
:
52960
,
"my_genes"
:
{
"doc_count"
:
8
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
8
}
]
}
}
}
},
{
"key"
:
"CMI-MPC"
,
"doc_count"
:
7
,
"genes"
:
{
"doc_count"
:
365
,
"my_genes"
:
{
"doc_count"
:
7
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
7
}
]
}
}
}
},
{
"key"
:
"CMI-ASC"
,
"doc_count"
:
6
,
"genes"
:
{
1.4.8 Analysis Endpoints
- 84/232 -
© 2015-2024
This portion of the output shows TCGA-GBM including 45 cases that have ssms in the gene ENSG00000155657 .
Example 2: The following demonstrates a use of the /analysis/top_mutated_genes_by_project endpoint. This will output the genes
that are mutated in the most cases in "TCGA-DLBC" and will count the mutations that have a HIGH or MODERATE impact on gene
"doc_count"
:
5745
,
"my_genes"
:
{
"doc_count"
:
6
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
6
}
]
}
}
}
},
{
"key"
:
"TARGET-WT"
,
"doc_count"
:
3
,
"genes"
:
{
"doc_count"
:
51
,
"my_genes"
:
{
"doc_count"
:
3
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
3
}
]
}
}
}
},
{
"key"
:
"TARGET-ALL-P3"
,
"doc_count"
:
2
,
"genes"
:
{
"doc_count"
:
66
,
"my_genes"
:
{
"doc_count"
:
2
,
"gene_id"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"ENSG00000155657"
,
"doc_count"
:
2
}
]
}
}
}
}
]
}
}
1.4.8 Analysis Endpoints
- 85/232 -
© 2015-2024
function. Note that the score field does not represent the number of mutations in a given gene, but a calculation that is used to
determine which genes have the greatest number of unique mutations.
1.4.8 Analysis Endpoints
- 86/232 -
© 2015-2024
1.4.8 Analysis Endpoints
- 87/232 -
© 2015-2024
Json Shell Response
{
"op"
:
"AND"
,
"content"
:[
{
"op"
:
"in"
,
"content"
:{
"field"
:
"case.project.project_id"
,
"value"
:[
"TCGA-DLBC"
]
}
},
{
"op"
:
"in"
,
"content"
:{
"field"
:
"case.ssm.consequence.transcript.annotation.vep_impact"
,
"value"
:[
"HIGH"
,
"MODERATE"
]
}
}
]
}
curl
"https://api.gdc.cancer.gov/analysis/top_mutated_genes_by_project?
fields=gene_id,symbol&filters=%7B%20%20%0A%20%20%20%22op%22%3A%22AND%20%20%20%22content%22%3A%5B%20%20%0A%20%20%20%20%20%20%7B%20%20%0A%20%20%20%20%20%20%20%20%20%22op%22%3A%22in%22%2C%0A
DLBC%22%0A%20%20%20%20%20%20%20%20%20%20%20%20%5D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%7B%20%20%0A%20%20%20%20%20%20%20%20%20%22op%22%3A%22in%2
{
"data"
:
{
"hits"
:
[
{
"symbol"
:
"KMT2D"
,
"gene_id"
:
"ENSG00000167548"
,
"_score"
:
13.0
},
{
"symbol"
:
"BTG2"
,
"gene_id"
:
"ENSG00000159388"
,
"_score"
:
13.0
},
{
"symbol"
:
"B2M"
,
"gene_id"
:
"ENSG00000166710"
,
"_score"
:
11.0
},
{
"symbol"
:
"PIM1"
,
"gene_id"
:
"ENSG00000137193"
,
"_score"
:
10.0
},
{
"symbol"
:
"IGHG1"
,
"gene_id"
:
"ENSG00000211896"
,
"_score"
:
10.0
},
{
"symbol"
:
"CARD11"
,
"gene_id"
:
"ENSG00000198286"
,
"_score"
:
10.0
},
{
"symbol"
:
"H1-4"
,
"gene_id"
:
"ENSG00000168298"
,
"_score"
:
9.0
},
{
"symbol"
:
"PCLO"
,
"gene_id"
:
"ENSG00000186472"
,
"_score"
:
9.0
},
{
"symbol"
:
"IGHG2"
,
"gene_id"
:
"ENSG00000211893"
,
"_score"
:
9.0
},
{
"symbol"
:
"FAT4"
,
"gene_id"
:
"ENSG00000196159"
,
"_score"
:
8.0
}
],
"pagination"
:
{
"count"
:
10
,
"total"
:
3500
,
"size"
:
10
,
"from"
:
0
,
"sort"
:
"None"
,
"page"
:
1
,
"pages"
:
350
}
},
"warnings"
:
{}
}
1.4.8 Analysis Endpoints
- 88/232 -
© 2015-2024
Example 3: The /analysis/top_mutated_cases_by_gene endpoint will generate information about the cases that are most affected by
mutations in a given number of genes. Below, the file count for each category is given for the cases most affected by mutations in
these 50 genes. The size of the output is limited to two cases with the size=2 parameter, but a higher value can be set by the user.
1.4.8 Analysis Endpoints
- 89/232 -
© 2015-2024
1.4.8 Analysis Endpoints
- 90/232 -
© 2015-2024
Shell Response
curl
"https://api.gdc.cancer.gov/analysis/top_mutated_cases_by_gene?
fields=diagnoses.age_at_diagnosis,diagnoses.primary_diagnosis,demographic.gender,demographic.race,demographic.ethnicity,case_id,summary.data_categories.file_count,summary.data_categories.
DLBC%22%7D%7D%2C%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22genes.gene_id%22%2C%22value%22%3A%5B%22ENSG00000166710%22%2C%22ENSG00000005339%22%2C%22ENSG00000083857%22%2C%2
{
"data"
:
{
"hits"
:
[
{
"summary"
:
{
"data_categories"
:
[
{
"file_count"
:
6
,
"data_category"
:
"Sequencing Reads"
},
{
"file_count"
:
14
,
"data_category"
:
"Biospecimen"
},
{
"file_count"
:
8
,
"data_category"
:
"Copy Number Variation"
},
{
"file_count"
:
16
,
"data_category"
:
"Simple Nucleotide Variation"
},
{
"file_count"
:
4
,
"data_category"
:
"Transcriptome Profiling"
},
{
"file_count"
:
3
,
"data_category"
:
"DNA Methylation"
},
{
"file_count"
:
8
,
"data_category"
:
"Clinical"
},
{
"file_count"
:
4
,
"data_category"
:
"Structural Variation"
},
{
"file_count"
:
1
,
"data_category"
:
"Proteome Profiling"
}
]
},
"case_id"
:
"eda9496e-be80-4a13-bf06-89f0cc9e937f"
,
"diagnoses"
:
[
{
"age_at_diagnosis"
:
18691
,
"primary_diagnosis"
:
"Malignant lymphoma, large B-cell, diffuse, NOS"
}
],
"demographic"
:
{
"ethnicity"
:
"hispanic or latino"
,
"gender"
:
"male"
,
"race"
:
"white"
},
"_score"
:
7.0
},
{
"summary"
:
{
"data_categories"
:
[
{
"file_count"
:
4
,
"data_category"
:
"Sequencing Reads"
},
{
"file_count"
:
13
,
"data_category"
:
"Biospecimen"
},
{
"file_count"
:
8
,
"data_category"
:
"Copy Number Variation"
},
{
"file_count"
:
16
,
"data_category"
:
"Simple Nucleotide Variation"
},
{
"file_count"
:
2
,
"data_category"
:
"Transcriptome Profiling"
},
{
"file_count"
:
3
,
"data_category"
:
"DNA Methylation"
},
{
"file_count"
:
8
,
"data_category"
:
"Clinical"
},
{
"file_count"
:
4
,
"data_category"
:
"Structural Variation"
}
]
},
"case_id"
:
"7a589441-11ef-4158-87e7-3951d86bc2aa"
,
"diagnoses"
:
[
1.4.8 Analysis Endpoints
- 91/232 -
© 2015-2024
Example 4: The /analysis/mutated_cases_count_by_project endpoint produces counts for the number of cases that have associated
ssm data in each project. The number of affected cases can be found under "case_with_ssm": {"doc_count": $case_count} .
1.4.8 Analysis Endpoints
- 92/232 -
© 2015-2024
1.4.8 Analysis Endpoints
- 93/232 -
© 2015-2024
Shell Response
curl
"https://api.gdc.cancer.gov/analysis/mutated_cases_count_by_project?size=0&pretty=true"
{
"took"
:
9
,
"timed_out"
:
false
,
"_shards"
:
{
"total"
:
12
,
"successful"
:
12
,
"skipped"
:
0
,
"failed"
:
0
},
"hits"
:
{
"total"
:
{
"value"
:
44451
,
"relation"
:
"eq"
},
"max_score"
:
null
,
"hits"
:
[]
},
"aggregations"
:
{
"projects"
:
{
"doc_count_error_upper_bound"
:
0
,
"sum_other_doc_count"
:
0
,
"buckets"
:
[
{
"key"
:
"FM-AD"
,
"doc_count"
:
18004
,
"case_summary"
:
{
"doc_count"
:
54012
,
"case_with_ssm"
:
{
"doc_count"
:
18004
}
}
},
{
"key"
:
"TARGET-AML"
,
"doc_count"
:
2492
,
"case_summary"
:
{
"doc_count"
:
10780
,
"case_with_ssm"
:
{
"doc_count"
:
22
}
}
},
{
"key"
:
"TARGET-ALL-P2"
,
"doc_count"
:
1587
,
"case_summary"
:
{
"doc_count"
:
5562
,
"case_with_ssm"
:
{
"doc_count"
:
717
}
}
},
{
"key"
:
"MP2PRT-ALL"
,
"doc_count"
:
1510
,
"case_summary"
:
{
"doc_count"
:
10472
,
"case_with_ssm"
:
{
"doc_count"
:
1508
}
}
},
{
"key"
:
"CPTAC-3"
,
"doc_count"
:
1235
,
"case_summary"
:
{
"doc_count"
:
8508
,
"case_with_ssm"
:
{
"doc_count"
:
1218
}
}
},
{
"key"
:
"TARGET-NBL"
,
"doc_count"
:
1132
,
"case_summary"
:
{
"doc_count"
:
3007
,
"case_with_ssm"
:
{
"doc_count"
:
220
}
}
},
{
"key"
:
"TCGA-BRCA"
,
"doc_count"
:
1098
,
"case_summary"
:
{
"doc_count"
:
9735
,
"case_with_ssm"
:
{
"doc_count"
:
1098
}
}
},
{
"key"
:
"MMRF-COMMPASS"
,
"doc_count"
:
995
,
"case_summary"
:
{
"doc_count"
:
3528
,
"case_with_ssm"
:
{
"doc_count"
:
959
1.4.8 Analysis Endpoints
- 94/232 -
© 2015-2024
Survival Analysis Endpoint
Survival plots are generated for different subsets of data, based on variants or projects, in the GDC Data Portal. The /analysis/
survival endpoint can be used to programmatically retrieve the raw data used to generate these plots and apply different filters.
Note that the fields and format parameters cannot be modified.
1.4.8 Analysis Endpoints
- 95/232 -
© 2015-2024
Example 1: A user wants to download data to generate a survival plot for cases from the project TCGA-DLBC.
1.4.8 Analysis Endpoints
- 96/232 -
© 2015-2024
1.4.8 Analysis Endpoints
- 97/232 -
© 2015-2024
Shell Response
curl
"https://api.gdc.cancer.gov/analysis/survival?
filters=%5B%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.project_id%22%2C%22value%22%3A%22TCGA-DLBC%22%7D%7D%5D&pretty=true"
{
"results"
:
[
{
"meta"
:
{
"id"
:
139834474037000
},
"donors"
:
[
{
"time"
:
1.0
,
"censored"
:
true
,
"survivalEstimate"
:
1
,
"id"
:
"dc87a809-95de-4eb7-a1c2-2650475f2d7e"
,
"submitter_id"
:
"TCGA-RQ-A6JB"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
17.0
,
"censored"
:
true
,
"survivalEstimate"
:
1
,
"id"
:
"4dd86ebd-ef16-4b2b-9ea0-5d1d7afef257"
,
"submitter_id"
:
"TCGA-RQ-AAAT"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
58
,
"censored"
:
false
,
"survivalEstimate"
:
1
,
"id"
:
"0bf573ac-cd1e-42d8-90cf-b30d7b08679c"
,
"submitter_id"
:
"TCGA-FA-A6HN"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
126.0
,
"censored"
:
true
,
"survivalEstimate"
:
0.9777777777777777
,
"id"
:
"f978cb0f-d319-4c01-b4c5-23ae1403a106"
,
"submitter_id"
:
"TCGA-FF-8047"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
132.0
,
"censored"
:
true
,
"survivalEstimate"
:
0.9777777777777777
,
"id"
:
"1843c82e-7a35-474f-9f79-c0a9af9aa09c"
,
"submitter_id"
:
"TCGA-FA-A4BB"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
132.0
,
"censored"
:
true
,
"survivalEstimate"
:
0.9777777777777777
,
"id"
:
"a43e5f0e-a21f-48d8-97e0-084d413680b7"
,
"submitter_id"
:
"TCGA-FA-8693"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
248
,
"censored"
:
false
,
"survivalEstimate"
:
0.9777777777777777
,
"id"
:
"0030a28c-81aa-44b0-8be0-b35e1dcbf98c"
,
"submitter_id"
:
"TCGA-FA-A7Q1"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
298.0
,
"censored"
:
true
,
"survivalEstimate"
:
0.9539295392953929
,
"id"
:
"f553f1a9-ecf2-4783-a609-6adca7c4c597"
,
"submitter_id"
:
"TCGA-FF-A7CQ"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
313
,
"censored"
:
false
,
"survivalEstimate"
:
0.9539295392953929
,
"id"
:
"f784bc3a-751b-4025-aab2-0af2f6f24266"
,
"submitter_id"
:
"TCGA-FF-A7CR"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
385.0
,
"censored"
:
true
,
"survivalEstimate"
:
0.929469807518588
,
"id"
:
"29e3d122-15a1-4235-a356-b1a9f94ceb39"
,
"submitter_id"
:
"TCGA-FF-A7CX"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
391
,
"censored"
:
false
,
"survivalEstimate"
:
0.929469807518588
,
"id"
:
"0e251c03-bf86-4ed8-b45d-3cbc97160502"
,
"submitter_id"
:
"TCGA-GS-A9U4"
,
"project_id"
:
"TCGA-DLBC"
},
{
"time"
:
427.0
,
"censored"
:
true
1.4.8 Analysis Endpoints
- 98/232 -
© 2015-2024
Example 2: Here the survival endpoint is used to compare two survival plots for TCGA-BRCA cases. One plot will display survival
information about cases with a particular mutation (in this instance: chr3:g.179234297A>G ) and the other plot will display
1.4.8 Analysis Endpoints
- 99/232 -
© 2015-2024
information about cases without that mutation. This type of query will also print the results of a chi-squared analysis between the
two subsets of cases.
1.4.8 Analysis Endpoints
- 100/232 -
© 2015-2024
Json Shell Json2
[
{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.project.project_id"
,
"value"
:
"TCGA-BRCA"
}
},
{
"op"
:
"="
,
"content"
:{
"field"
:
"gene.ssm.ssm_id"
,
"value"
:
"edd1ae2c-3ca9-52bd-a124-b09ed304fcc2"
}
}
]
},
{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.project.project_id"
,
"value"
:
"TCGA-BRCA"
}
},
{
"op"
:
"excludeifany"
,
"content"
:{
"field"
:
"gene.ssm.ssm_id"
,
"value"
:
"edd1ae2c-3ca9-52bd-a124-b09ed304fcc2"
}
}
]
}
]
curl
"https://api.gdc.cancer.gov/analysis/survival?
filters=%5B%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.project_id%22%2C%22value%22%3A%22TCGA-
BRCA%22%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22gene.ssm.ssm_id%22%2C%22value%22%3A%22edd1ae2c-3ca9-52bd-a124-
b09ed304fcc2%22%7D%7D%5D%7D%2C%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.project_id%22%2C%22value%22%3A%22TCG
BRCA%22%7D%7D%2C%7B%22op%22%3A%22excludeifany%22%2C%22content%22%3A%7B%22field%22%3A%22gene.ssm.ssm_id%22%2C%22value%22%3A%22edd1ae2c-3ca9-52bd-a124-
b09ed304fcc2%22%7D%7D%5D%7D%5D&pretty=true"
{
"overallStats"
:
{
"degreesFreedom"
:
1
,
"chiSquared"
:
0.8577589072612264
,
"pValue"
:
0.35436660628146011
},
"results"
:
[
{
"donors"
:
[
{
"survivalEstimate"
:
1
,
"id"
:
"a991644b-3ee6-4cda-acf0-e37de48a49fc"
,
"censored"
:
true
,
"time"
:
10
},
{
"survivalEstimate"
:
1
,
"id"
:
"2e1e3bf0-1708-4b65-936c-48b89eb8966a"
,
"censored"
:
true
,
"time"
:
19
},
(
trun
ca
te
d)
],
"meta"
:
{
"id"
:
140055251282040
}
},
{
"donors"
:
[
{
"survivalEstimate"
:
1
,
"id"
:
"5e4187c9-98f8-4bdb-a8da-6a914e96f47a"
,
"censored"
:
true
,
"time"
:
-31
},
(
trun
ca
te
d)
1.4.8 Analysis Endpoints
- 101/232 -
© 2015-2024
The output represents two sets of coordinates delimited as objects with the donors tag. One set of coordinates will generate a
survival plot representing TCGA-BRCA cases that have the mutation of interest and the other will generate a survival plot for the
remaining cases in TCGA-BRCA.
Example 3: Custom survival plots can be generated using the GDC API. For example, a user could generate survival plot data
comparing patients with a mutation in genes associated with a biological pathway with patients without mutations in that pathway.
The following example compares a patient with at least one mutation in either gene
ENSG00000141510 or ENSG00000155657 with
patients that do not have mutations in these genes.
Query Shell
[
{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.project.project_id"
,
"value"
:
"TCGA-BRCA"
}
},
{
"op"
:
"="
,
"content"
:{
"field"
:
"gene.gene_id"
,
"value"
:[
"ENSG00000141510"
,
"ENSG00000155657"
]
}
}
]
},
{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.project.project_id"
,
"value"
:
"TCGA-BRCA"
}
},
{
"op"
:
"excludeifany"
,
"content"
:{
"field"
:
"gene.gene_id"
,
"value"
:[
"ENSG00000141510"
,
"ENSG00000155657"
]
}
}
]
}
]
curl
"https://api.gdc.cancer.gov/analysis/survival?
filters=%5B%0D%0A%7B%0D%0A%22op%22%3A%22and%22%2C%0D%0A%22content%22%3A%5B%0D%0A%7B%0D%0A%22op%22%3A%22%3D%22%2C%0D%0A%22content%22%3A%7B%0D%0A%22field%22%3A%22cases.project.project_id%22
BRCA%22%0D%0A%7D%0D%0A%7D%2C%0D%0A%7B%0D%0A%22op%22%3A%22%3D%22%2C%0D%0A%22content%22%3A%7B%0D%0A%22field%22%3A%22gene.gene_id%22%2C%0D%0A%22value%22%3A%5B%22ENSG00000141510%22%2C%22ENSG0
BRCA%22%0D%0A%7D%0D%0A%7D%2C%0D%0A%7B%0D%0A%22op%22%3A%22excludeifany%22%2C%0D%0A%22content%22%3A%7B%0D%0A%22field%22%3A%22gene.gene_id%22%2C%0D%0A%22value%22%3A%5B%22ENSG00000141510%22%2
1.4.8 Analysis Endpoints
- 102/232 -
© 2015-2024
Example 4: Survival plots can be even more customizable when sets of case IDs are used. Two sets of case IDs (or barcodes) can
be retrieved in a separate step based on custom criteria and compared in a survival plot. See below for an example query.
Json Shell
[{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.submitter_id"
,
"value"
:[
"TCGA-HT-A74J"
,
"TCGA-43-A56U"
,
"TCGA-GM-A3XL"
,
"TCGA-A1-A0SQ"
,
"TCGA-K1-A6RV"
,
"TCGA-J2-A4AD"
,
"TCGA-XR-A8TE"
]
}
},
{
"op"
:
"="
,
"content"
:{
"field"
:
"cases.submitter_id"
,
"value"
:[
"TCGA-55-5899"
,
"TCGA-55-6642"
,
"TCGA-55-7907"
,
"TCGA-67-6216"
,
"TCGA-75-5146"
,
"TCGA-49-4510"
,
"TCGA-78-7159"
]
}
}]
curl
"https://api.gdc.cancer.gov/analysis/survival?
filters=%5B%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.submitter_id%22%2C%22value%22%3A%5B%22TCGA-HT-A74J%22%2C%22TCGA-43-A56U%22%2C%22TCGA-
GM-A3XL%22%2C%22TCGA-A1-A0SQ%22%2C%22TCGA-K1-A6RV%22%2C%22TCGA-J2-A4AD%22%2C%22TCGA-XR-
A8TE%22%5D%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.submitter_id%22%2C%22value%22%3A%5B%22TCGA-55-5899%22%2C%22TCGA-55-6642%22%2C%22TCGA-55-7907%22%2C%2
1.4.8 Analysis Endpoints
- 103/232 -
© 2015-2024
1.5 BAM Slicing
The GDC API provides remote BAM slicing functionality that enables downloading of specific parts of a BAM file instead of the
whole file. This functionality can be accessed at the slicing endpoint, using a syntax similar to that of widely used bioinformatics
tools such as samtools .
1.5.1 About the slicing endpoint
The slicing endpoint accepts HTTP GET requests in the form of a URL, and HTTP POST requests that carry a JSON payload.
POST requests are more appropriate in cases where query parameters make the GET URL very long.
The response will be a BAM-formatted file containing the header of the source BAM file, as well as any alignment records that are
found to overlap the specified regions, sorted by chromosomal coordinate.
Please note the following:
• The functionality of this API differs from the usual functionality of
samtools in that alignment records that overlap multiple
regions will not be returned multiple times.
• A request with no region or gene specified will return the BAM header, which makes it easy to inspect the references to which
the alignment records were aligned.
• A request for regions that are not included in the source BAM is not considered an error, and is treated the same as if no
records existed for the region.
• Examples provided for BAM slicing functionality are intended for use with GDC harmonized data (i.e. BAM files available in the
GDC Data Portal).
• Bam slicing does not create an associated bam index (.bai) file. For applications requiring a .bai file users will need to generate
this file from the bam slice using a tool and command such as
samtools index .
Query Parameters
The following query parameters and JSON fields are supported:
NOTE: The successfully sliced BAM will contain all reads that overlap (entirely or partially) with the specified region or gene. It is
possible to specify an open-ended region, e.g. chr2:10000 , which would return all reads that (completely or partially) overlap with
the region of chromosome 2 from position 10,000 to the end of the chromosome.
JSON Schema
JSON payloads can be syntactically verified using the following JSON schema:
Description Query
Parameter
JSON Field Query format
entire chromosome, or a position or region on the
chromosome, specified using chromosomal coordinates
region regions region=(:(-)?)?
region specified using a HGNC / GENCODE v36 gene name gencode gencode gencode=
{
"$schema": "http://json-schema.org/schema#",
"type": "object",
"properties": {
"regions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9]+(:([0-9]+)?(-[0-9]+)?)?$"
}
},
"gencode": {
"type": "array",
"items": {
1.5 BAM Slicing
- 104/232 -
© 2015-2024
1.5.2 Examples: Specifying a region
The following two requests are examples of BAM slicing using region(s).
1.5.3 Examples: Specifying a gene
The following two requests are examples of BAM slicing using HGNC / GENCODE v36 gene name(s).
1.5.4 Examples: Specifying unmapped reads
Unmapped reads are found in GDC BAM files. You may request these reads by using the following commands.
"type": "string"
}
}
}
}
Regions_GET Regions_POST_Payload Regions_POST Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/slicing/view/2912e314-f6a7-4f4a-94ac-20db2c8f793b?
region=chr1&region=chr2:10000&region=chr3:10000-20000'
--output
get_regions_slice.bam
{
"regions"
:
[
"chr1"
,
"chr2:10000"
,
"chr3:10000-20000"
]
}
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
https://api.gdc.cancer.gov/slicing/view/2912e314-f6a7-4f4a-94ac-20db2c8f793b
--header
"Content-Type: application/
json"
-d@Payload
--output
post_regions_slice.bam
Response:
HTTP/1.1 206
<bam_data_stream>
Gencode_GET Gencode_POST_Payload Gencode_POST Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/slicing/view/2912e314-f6a7-4f4a-94ac-20db2c8f793b?gencode=BRCA1'
--output
get_brca1_slice.bam
{
"gencode"
:
[
"BRCA1"
,
"BRCA2"
]
}
curl
--header
"X-Auth-Token:
$token
"
--request
POST
https://api.gdc.cancer.gov/slicing/view/2912e314-f6a7-4f4a-94ac-20db2c8f793b
--header
"Content-Type: application/
json"
-d@Payload
--output
post_brca12_slice.bam
Response:
HTTP/1.1 206
<bam_data_stream>
1.5.2 Examples: Specifying a region
- 105/232 -
© 2015-2024
After downloading, the sliced BAM file can be converted to SAM using the following command if samtools is installed on the user's
system:
1.5.5 Errors
When slicing cannot be performed, the GDC API will provide JSON error responses and HTTP error codes.
JSON Error Responses
JSON error responses have the following structure:
For example, when making a request for a protected BAM without supplying a GDC authentication token:
HTTP error codes
Potential HTTP error codes include:
GET POST_Payload POST Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/slicing/view/dc87e1b8-d8b7-4837-88ea-fb7f017b3c69?region=unmapped'
--output
get_regions_slice.bam
{
"regions"
:
[
"unmapped"
]
}
curl
--header
"X-Auth-Token:
$token
"
--request
POST
https://api.gdc.cancer.gov/slicing/view/dc87e1b8-d8b7-4837-88ea-fb7f017b3c69
--header
"Content-Type: application/
json"
-d@Payload
--output
get_regions_slice.bam
Response:
HTTP/1.1 206
<bam_data_stream>
samtools view -h brca1_slice.bam -o brca1_slice.sam
{
"error": "<error-message>"
}
Shell Response
curl
https://api.gdc.cancer.gov/v0/slicing/view/15b0bf8e-ff20-41ab-8366-a495c11b30be
HTTP/1.1 403 FORBIDDEN
{
"error": "Please specify a X-Auth-Token"
}
Error Code Description
400 Bad Request -- The regions specified are malformed
403 Unauthorized -- The user could not be authenticated
403 Unauthorized -- The user is not authorized for access to the source BAM
404 Not Found -- No BAM is specified
404 Not Found -- No BAM can be found for the specified GDC BAM ID
504 BAI Not Found -- No BAI can be found for the BAM
1.5.5 Errors
- 106/232 -
© 2015-2024
Transfer Errors
In the case that an error occurs during transfer of the resulting BAM, the BGZF EOF marker will not be present. This early
truncation of the BAM file will cause errors if the file is used as input to other programs. For example, samtools will provide the
error "EOF marker is absent".
Early truncation can arise when connection is interrupted or when slicing fails due to BAM corruption.
1.5.5 Errors
- 107/232 -
© 2015-2024
1.6 Submission
1.6.1 Overview
The GDC Submission API uses methods and endpoints that are distinct from those that drive the functionality of the GDC Data
Portal. In particular, data and metadata that are in the process of being submitted can only be queried using GraphQL, and not
the methods described in Search and Retrieval.
This section describes the GDC API's submission functionality, including methods for submitting, deleting, updating, searching,
and retrieving data and metadata.
1.6.2 Submission endpoint
Constructing the endpoint URL
The endpoint for submitting data to a specific project in the GDC is constructed as follows:
where [API_version/] is the optional API version component (see Getting Started).
The values of Program.name and Project.code can be obtained from the project URL on the GDC Data Submission Portal:
For more information about program name and project code see The GDC Data Model section.
EXAMPLE
The following are URL examples for a project with Program.name "TCGA" and Project.code "ALCH":
• Submission Portal URL: https://portal.gdc.cancer.gov/submission/TCGA/ALCH/dashboard
• API submission endpoint (versioned): https://api.gdc.cancer.gov/v0/submission/TCGA/ALCH
• API submission endpoint (unversioned): https://api.gdc.cancer.gov/submission/TCGA/ALCH
1.6.3 Submission Formats
Metadata Formats
JSON AND TSV
The GDC API accepts project metadata in JSON and TSV formats for the purpose of creating entities in the GDC Data Model. This
includes clinical and biospecimen metadata such as disease name and stage, patient age, sample type, and certain details about
the types of data collected. Upon successful data submission and project release, this metadata is indexed and becomes available
for queries by data users via the GDC Data Portal and the GDC API. See GDC Data Model (below) for information on accepted
metadata elements and instructions for obtaining templates for metadata submission.
Content-Type Header
JSON is the default format for metadata submission. Submission API calls with JSON payloads should include the HTTP header
Content-Type: application/json . Requests with TSV payloads must instead include the header Content-Type: text/tsv .
Binary Mode
Metadata files must be uploaded in raw, unencoded form. Binary mode should be used, if available, to ensure that file contents are
not encoded by the upload tool before transmission. For example, when using the curl command-line tool, the --data-binary
switch should be used instead of --data . The --data-binary switch is required for uploading TSV files.
https://api.gdc.cancer.gov/[API_version/]submission/Program.name/Project.code
https://portal.gdc.cancer.gov/submission/Program.name/Project.code/dashboard
1.6 Submission
- 108/232 -
© 2015-2024
Data File Formats
The GDC API accepts a variety of data files after their metadata has been registered: BAM and FASTQ files, clinical and
biospecimen supplements, slide images, and other file types. Supported data file formats are listed on the GDC Data Dictionary.
1.6.4 GDC Data Model
Submitters should review the GDC Data Model documentation and the GDC Data Dictionary before initiating submission.
UUIDs
Submitters can assign UUIDs to all submittable entities other than those that correspond to files (entities in categories data_file
or metadata_file ). If the submitter does not provide a UUID, it will be assigned by the GDC and returned in the API response upon
successful completion of the submission transaction. See Appendix C for details of the API response format. To learn more about
UUIDs see the GDC Data Model documentation.
Submitter IDs
In addition to id , many entities also include a submitter_id field. This field can contain any string (e.g. a "barcode") that the
submitter wishes to use to identify the entity. Typically this string identifies a corresponding entry in submitter's records. The
GDC's only requirement with respect to submitter_id is that it be a string that is unique for all entities within a project. The GDC
Submission API requires a submitter_id for most entities.
Note: For case entities, submitter_id must correspond to a submitted_subject_id of a study participant registered with the project
in dbGaP.
GDC Data Dictionary Endpoints
Information in the GDC Data Dictionary can be accessed programmatically as described below.
SUBMISSION TEMPLATES
Submission templates are accessible programmatically at the templates endpoint. Template format ( json , tsv or csv ) is specified
using the format parameter.
For example, the JSON template for case entities can be obtained from:
In addition to case , templates for the following entities can be downloaded
Biospecimen:
Clinical:
Data Files:
https://api.gdc.cancer.gov/v0/submission/template/case?format=json
sample
portion
analyte
aliquot
read_group
slide
demographic
diagnosis
exposure
family_history
treatment
follow_up
molecular_test
analysis_metadata
biospecimen_supplement
1.6.4 GDC Data Model
- 109/232 -
© 2015-2024
ENTITY JSON SCHEMAS
The entire collection of GDC entity schemas can be downloaded from the dictionary endpoint:
Individual schemas can be downloaded by specifying entity type. For example, the JSON schema for case entities can be found at:
1.6.5 Making Requests to the Submission API
Requests to create or update entities in the GDC must specify the entity type , the entity id or submitter_id , relationships (links)
that the entity has to existing entities in the GDC Data Model, and entity properties as defined by the GDC Data Dictionary. To
delete entities, only the id property is required. The general format of GDC API submission requests and responses is provided in
Appendix C.
1.6.6 Submission Transactions
Submission of data to the GDC involves a series of transactions initiated by the submitter, that create and link entities according to
the GDC Data Model. With the exception of program , which is an administrative entity created by the GDC, all new entities must be
linked, at creation, to existing entities or to new entities being created in the same transaction. For example, a submitter cannot
create a portion entity unless the submitter either (1) has previously created the corresponding case and sample entities, or (2) is
creating those entities in the same transaction. This also means that entities cannot be deleted if they have "child" entities
attached to them.
If multiple entities are being created and/or updated in a transaction, and an error is encountered for one of the entities, then the
transaction will fail and no changes will be made to the GDC.
Dry Run Transactions
The submission endpoint provides a _dry_run mode that simulates submission transactions without making changes to the GDC.
This mode is activated by appending /_dry_run to the end of a submission endpoint.
clinical_supplement
experiment_metadata
pathology_report
run_metadata
slide_image
submitted_unaligned_reads
submitted_aligned_reads
submitted_genomic_profile
https://api.gdc.cancer.gov/v0/submission/_dictionary/_all
https://api.gdc.cancer.gov/v0/submission/_dictionary/case
1.6.5 Making Requests to the Submission API
- 110/232 -
© 2015-2024
The following is an example of a POST request, that simulates creating an entity in dry run mode:
DRY RUN COMMIT
For convenience, the GDC enables users to commit earlier _dry_run transactions instead of uploading the same data again to
execute the changes. This commit action is allowed on transactions that (1) have not been previously committed and (2) were
successful dry_run transactions.
Note that the commit action is a separate transaction with its own transaction id, and it can be executed asynchronously. If the
state of the submission project has changed in a way that would make the original _dry_run transaction invalid if it were run again
(e.g. entities with the same submitter_id have since been created in another transaction), then the commit action will fail.
To commit a transaction, submit a POST or PUT request to /submission/Program.name/Project.code/transactions/transaction_id/commit ,
replacing Program.name , Project.code , and transaction_id with values associated with the transaction.
Request Command Response
{
"project_id"
:
"GDC-INTERNAL"
,
"type"
:
"case"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
,
"disease_type"
:
"Blood Vessel Tumors"
,
"primary_site"
:
"Base of tongue"
,
"projects"
:
{
"code"
:
"INTERNAL"
}
}
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL/_dry_run
{
"cases_related_to_created_entities_count"
:
0
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
200
,
"created_entity_count"
:
1
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"bfc1fb29-28db-4137-8379-3d1693ce3423"
,
"related_cases"
:
[],
"type"
:
"case"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction would have been successful. User selected dry run option, transaction aborted, no data written to database."
,
"success"
:
true
,
"transaction_id"
:
5834800
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
Command Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
https://api.gdc.cancer.gov/v0/submission/GDC/INTERNAL/transactions/467/commit?async
=
true
{
"code"
:
200
,
"message"
:
"Transaction submitted."
,
"transaction_id"
:
468
,
}
1.6.6 Submission Transactions
- 111/232 -
© 2015-2024
DRY RUN CLOSE
The GDC Submission API also provides a close action on _dry_run transactions. This close action is allowed on _dry_run
transactions that have not been previously closed. Closing a _dry_run transaction prevents it from being committed in the future.
To close a transaction, submit a POST or PUT request to /submission/Program.name/Project.code/transactions/transaction_id/close ,
replacing Program.name , Project.code , and transaction_id with values associated with the transaction.
Asynchronous Transactions
The submission endpoint provides an asynchronous mode that provides immediate response and executes submission transactions
in the background. This mode is activated by appending ?async=true to the end of a submission endpoint. The API will respond
with the transaction_id which can be used to look up the result of the transaction at a later time via the GraphQL endpoint. If the
server has too many asynchronous jobs scheduled already, your request to schedule a transaction may fail.
EXAMPLE
The following is an example of a PUT request, that creates a case asynchronously:
Command Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
https://api.gdc.cancer.gov/v0/submission/GDC/INTERNAL/transactions/467/close
{
"code"
:
200
,
"message"
:
"Closed transaction."
,
"transaction_id"
:
467
}
Request Command Response
{
"project_id"
:
"GDC-INTERNAL"
,
"type"
:
"case"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
,
"disease_type"
:
"Blood Vessel Tumors"
,
"primary_site"
:
"Base of tongue"
,
"projects"
:
{
"code"
:
"INTERNAL"
}
}
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL?async
=
true
{
"code"
:
200
,
"message"
:
"Transaction submitted."
,
"transaction_id"
:
467
,
}
1.6.6 Submission Transactions
- 112/232 -
© 2015-2024
The following is a GraphQL request that looks up the state of the above transaction:
TRANSACTION STATUS
The following transaction fields can be queried using GraphQL and are helpful in determining the status of a transaction:
Note: To check whether a dry run transaction was committed successfully, check the state of the transaction that executed the
commit. The state of the dry run transaction itself does not represent the status of a subsequent commit.
1.6.7 Creating and Updating Entities
The GDC Submission API supports HTTP POST and HTTP PUT methods for creating entities:
• POST will create entities that do not exist, and will fail if any of the entities in the transaction already exist in the GDC.
• PUT will create new entities and update existing entities, and identify which entities were created or updated in the API
response.
The GDC suggests using POST for creating new entities, and using PUT only for updating entities. This helps to avoid inadvertent
entity updates that can occur when using PUT for creating entities.
Note: Once a relationship has been created between two entities, it cannot be removed by updating an entity. To remove a
relationship, the child entity must be deleted.
Example: Creating and Updating Case Entities (JSON)
In this example, a case entity is created using POST. Then an attempt is made to create the same entity again using POST, resulting
in an error. Then the originally created entity is updated (with the same information) using PUT.
GraphQL_Request GraphQL_Response
query
{
transaction_log
(
id
:
467
)
{
is_dry_run
committed_by
state
}
}
{
"
data
":
{
"
transaction_log
":
[
{
"
committed_by
":
null
,
"
is_dry_run
":
false
,
"
state
":
"
FAILED
"
}
]
}
}
Field Type Description
id ID Transaction identifier
is_dry_run Boolean Indicates whether the transaction is a dry run
closed Boolean For dry run transactions, indicates whether the transaction has been closed to
prevent it from being committed in the future.
committable Boolean Indicates whether the transaction can be committed (i.e. it is a successful dry run
transaction that has not been committed previously and has not been closed)
state String Indicates the state of the transaction: PENDING , SUCCEEDED , FAILED (due to user
error), or ERRORED (due to system error)
committed_by ID The ID of the transaction that committed this transaction
1.6.7 Creating and Updating Entities
- 113/232 -
© 2015-2024
The JSON in the request was generated using the case JSON template that can be obtained from the GDC Data Dictionary Viewer
and from https://api.gdc.cancer.gov/v0/submission/template/case?format=json .
Note: For case entities, submitter_id must correspond to a submitted_subject_id of a study participant registered with the project
in dbGaP.
1.6.7 Creating and Updating Entities
- 114/232 -
© 2015-2024
1.6.7 Creating and Updating Entities
- 115/232 -
© 2015-2024
Request1 Command1 Response1 Command2 Response2 Command3 Response3
{
"project_id"
:
"GDC-INTERNAL"
,
"type"
:
"case"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
,
"disease_type"
:
"Blood Vessel Tumors"
,
"primary_site"
:
"Base of tongue"
,
"projects"
:
{
"code"
:
"INTERNAL"
}
}
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL
{
"cases_related_to_created_entities_count"
:
0
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
200
,
"created_entity_count"
:
1
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"bfc1fb29-28db-4137-8379-3d1693ce3423"
,
"related_cases"
:
[],
"type"
:
"case"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction would have been successful. User selected dry run option, transaction aborted, no data written to database."
,
"success"
:
true
,
"transaction_id"
:
5834800
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/TCGA/
ALCH
{
"cases_related_to_created_entities_count"
:
0
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
400
,
"created_entity_count"
:
0
,
"entities"
:
[
{
"action"
:
null
,
"errors"
:
[
{
"keys"
:
[
"id"
],
"message"
:
"Cannot create an entity with an id that already exists."
,
"type"
:
"NOT_UNIQUE"
}
],
"id"
:
null
,
"related_cases"
:
[],
"type"
:
"case"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"valid"
:
false
,
"warnings"
:
[]
}
],
"entity_error_count"
:
1
,
"message"
:
"Transaction aborted due to 1 invalid entity."
,
"success"
:
false
,
"transaction_id"
:
5834802
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
curl
--header
"X-Auth-Token:
$token
"
--request
PUT
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL
{
"cases_related_to_created_entities_count"
:
0
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
200
,
"created_entity_count"
:
0
,
"entities"
:
[
{
"action"
:
"update"
,
1.6.7 Creating and Updating Entities
- 116/232 -
© 2015-2024
Example: Creating an Aliquot Entity (JSON)
In this example, an aliquot entity and a sample entity are created in a single transaction. The aliquot is linked to sample which is
linked to case . The first request is an example of using submitter_id properties to link entities together. The second request is an
example of using UUIDs for creating the links.
1.6.7 Creating and Updating Entities
- 117/232 -
© 2015-2024
REQUEST 1: CREATING LINKS USING SUBMITTER_ID
Request Command Response
[
{
"type"
:
"sample"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093"
,
"tissue_type"
:
"Tumor"
,
"preservation_method"
:
"Fresh"
,
"specimen_type"
:
"Whole Bone Marrow"
,
"tumor_descriptor"
:
"Primary"
,
"cases"
:
{
"submitter_id"
:
"GDC-INTERNAL-000093"
}
},
{
"type"
:
"aliquot"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093-ALIQUOT000093"
,
"samples"
:
{
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093"
}
}
]
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL
{
"cases_related_to_created_entities_count"
:
1
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
201
,
"created_entity_count"
:
2
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"0a877533-0c85-4a7e-9309-733ccf295c1b"
,
"related_cases"
:
[
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"type"
:
"sample"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093"
}
],
"valid"
:
true
,
"warnings"
:
[]
},
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"45c57067-c92d-453b-8b6d-14a3fe08f802"
,
"related_cases"
:
[
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"type"
:
"aliquot"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093-ALIQUOT000093"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction successful."
,
"success"
:
true
,
"transaction_id"
:
5835160
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
1.6.7 Creating and Updating Entities
- 118/232 -
© 2015-2024
REQUEST 2: CREATING LINKS USING UUID
Request Command Response
[
{
"type"
:
"sample"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093"
,
"tissue_type"
:
"Tumor"
,
"preservation_method"
:
"Fresh"
,
"specimen_type"
:
"Whole Bone Marrow"
,
"tumor_descriptor"
:
"Primary"
,
"cases"
:
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
}
},
{
"type"
:
"aliquot"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093-ALIQUOT000093"
,
"samples"
:
{
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093"
}
}
]
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/submission/GDC/
INTERNAL
{
"cases_related_to_created_entities_count"
:
1
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
201
,
"created_entity_count"
:
2
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"9684fd7c-97b5-42a2-b350-2d86d41bbfdb"
,
"related_cases"
:
[
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"type"
:
"sample"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093"
}
],
"valid"
:
true
,
"warnings"
:
[]
},
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"cd5613ef-acb8-4b56-af4b-8bf3ab0e09d8"
,
"related_cases"
:
[
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"type"
:
"aliquot"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093-SAMPLE000093-ALIQUOT000093"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction successful."
,
"success"
:
true
,
"transaction_id"
:
5835208
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
1.6.7 Creating and Updating Entities
- 119/232 -
© 2015-2024
Example: Creating Two Samples (TSV)
In this example, a TSV file containing metadata for two samples is uploaded to the GDC in dry run mode.
Example: Updating a Sample Entity (JSON)
Entities can be updated using a very similar process to what is shown above.
UPDATING A SAMPLE
New nodes are created in Request1. Nodes in state validated are updated in Request2.
Request Command Reponse
type project_id submitter_id cases.submitter_id specimen_type tissue_type tumor_descriptor preservation_method
sample GDC-INTERNAL GDC-INTERNAL-000093-sampleA GDC-INTERNAL-000093 Solid Tissue Tumor Primary Frozen
sample GDC-INTERNAL GDC-INTERNAL-000093-sampleB GDC-INTERNAL-000093 Solid Tissue Normal Not Reported Frozen
curl
--header
"X-Auth-Token:
$token
"
--header
'Content-Type: text/tsv'
--request
PUT
--data-binary
@Samples.tsv
'https://api.gdc.cancer.gov/submission/GDC/INTERNAL/
_dry_run'
{
"cases_related_to_created_entities_count"
:
1
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
200
,
"created_entity_count"
:
2
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"c3d401f1-d505-4240-b801-dc2b389ddea1"
,
"related_cases"
:
[
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"type"
:
"sample"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093-sampleA"
}
],
"valid"
:
true
,
"warnings"
:
[]
},
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"d3c4be95-9c69-4e8e-9f37-61db455ded7a"
,
"related_cases"
:
[
{
"id"
:
"a00f076e-d694-47dd-8e50-24c28e90fd6a"
,
"submitter_id"
:
"GDC-INTERNAL-000093"
}
],
"type"
:
"sample"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"GDC-INTERNAL-000093-sampleB"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction would have been successful. User selected dry run option, transaction aborted, no data written to database."
,
"success"
:
true
,
"transaction_id"
:
5835321
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
1.6.7 Creating and Updating Entities
- 120/232 -
© 2015-2024
1.6.7 Creating and Updating Entities
- 121/232 -
© 2015-2024
1.6.7 Creating and Updating Entities
- 122/232 -
© 2015-2024
Request1 Conmmand1 Response1 Request2 Command2 Response2
[
{
"type"
:
"case"
,
"submitter_id"
:
"QA-REGRESSION-0002"
,
"projects"
:
{
"code"
:
"REGRESSION"
}
},
{
"type"
:
"sample"
,
"submitter_id"
:
"QA-REGRESSION-0002-SAMPLE000001"
,
"sample_type"
:
"Primary Tumor"
,
"sample_type_id"
:
"01"
,
"cases"
:
{
"submitter_id"
:
"QA-REGRESSION-0002"
}
},
{
"type"
:
"aliquot"
,
"submitter_id"
:
"QA-REGRESSION-0002-SAMPLE000001-ALIQUOT000001"
,
"samples"
:
{
"submitter_id"
:
"QA-REGRESSION-0002-SAMPLE000001"
}
}
]
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@sample.json
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/QA/
REGRESSION
{
"cases_related_to_created_entities_count"
:
1
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
201
,
"created_entity_count"
:
3
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"3a750ae8-8e63-472e-852e-8e514a0c1550"
,
"related_cases"
:
[],
"type"
:
"case"
,
"unique_keys"
:
[
{
"project_id"
:
"QA-REGRESSION"
,
"submitter_id"
:
"QA-REGRESSION-0002"
}
],
"valid"
:
true
,
"warnings"
:
[]
},
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"8a1872e6-c5e6-4f39-b9fe-15ecf45715c7"
,
"related_cases"
:
[
{
"id"
:
"3a750ae8-8e63-472e-852e-8e514a0c1550"
,
"submitter_id"
:
"QA-REGRESSION-0002"
}
],
"type"
:
"sample"
,
"unique_keys"
:
[
{
"project_id"
:
"QA-REGRESSION"
,
"submitter_id"
:
"QA-REGRESSION-0002-SAMPLE000001"
}
],
"valid"
:
true
,
"warnings"
:
[]
},
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"e9279137-92b4-41ab-be28-a03e32e6fac7"
,
"related_cases"
:
[
{
"id"
:
"3a750ae8-8e63-472e-852e-8e514a0c1550"
,
"submitter_id"
:
"QA-REGRESSION-0002"
}
],
"type"
:
"aliquot"
,
"unique_keys"
:
[
{
"project_id"
:
"QA-REGRESSION"
,
"submitter_id"
:
"QA-REGRESSION-0002-SAMPLE000001-ALIQUOT000001"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction successful."
,
"success"
:
true
,
"transaction_id"
:
920117
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
1.6.7 Creating and Updating Entities
- 123/232 -
© 2015-2024
1.6.8 Retrieving Entities
Entities Endpoint
JSON objects representing submitted entities can be retrieved with a GET request to the entities endpoint. This endpoint
retrieves entities by UUID. A single UUID or a comma-separated list of UUIDs can be passed to this endpoint as a query.
Export Endpoint
The export endpoint provides additional functionality for exporting entities from the GDC submission system. The ids parameter
accepts a UUID or a comma-separated list of UUIDs. The format parameter allows the user to specify the preferred format of the
Command Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
https://api.gdc.cancer.gov/v0/submission/TCGA/ALCH/entities/fbf69646-5904-4f95-92d6-692bde658f05
{
"entities"
:
[
{
"program"
:
"TCGA"
,
"project"
:
"ALCH"
,
"properties"
:
{
"created_datetime"
:
"2016-04-14T08:44:43.361800-05:00"
,
"id"
:
"fbf69646-5904-4f95-92d6-692bde658f05"
,
"project_id"
:
"TCGA-ALCH"
,
"projects"
:
[
{
"id"
:
"d9906779-f1da-5d9f-9caa-6d5ecb2e3cd6"
,
"submitter_id"
:
null
}
],
"state"
:
"validated"
,
"submitter_id"
:
"TCGA-ALCH-000001"
,
"type"
:
"case"
,
"updated_datetime"
:
"2016-04-14T21:29:28.401212-05:00"
}
}
]
}
1.6.8 Retrieving Entities
- 124/232 -
© 2015-2024
API response: JSON, TSV, or CSV. When the with_children parameter is set to with_children , the response includes the metadata
stored in all "child" entities of the entity being requested. The export endpoint accepts GET requests.
1.6.8 Retrieving Entities
- 125/232 -
© 2015-2024
1.6.8 Retrieving Entities
- 126/232 -
© 2015-2024
Command Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/v0/submission/TCGA/ALCH/export?ids=11f8321-832f-4a8b-8384-
a2f6256557e0&format=json&with_children=with_children'
{
"case"
:
[
{
"tissue_source_sites"
:
[],
"submitter_id"
:
"TCGA-ALCH-000026"
,
"project_id"
:
"TCGA-ALCH"
,
"type"
:
"case"
,
"id"
:
"11f83251-832f-4a8b-8384-a2f6256557e0"
,
"projects"
:
[
{
"code"
:
"ALCH"
,
"id"
:
"d9906779-f1da-5d9f-9caa-6d5ecb2e3cd6"
}
]
}
],
"sample"
:
[
{
"sample_type_id"
:
"10"
,
"time_between_excision_and_freezing"
:
null
,
"oct_embedded"
:
"false"
,
"tumor_code_id"
:
null
,
"submitter_id"
:
"Blood-00001_api26"
,
"intermediate_dimension"
:
null
,
"id"
:
"23308708-6a63-471e-947c-6a93c6e85983"
,
"time_between_clamping_and_freezing"
:
null
,
"pathology_report_uuid"
:
null
,
"tumor_descriptor"
:
null
,
"sample_type"
:
"Blood Derived Normal"
,
"project_id"
:
"TCGA-ALCH"
,
"current_weight"
:
null
,
"composition"
:
null
,
"is_ffpe"
:
null
,
"shortest_dimension"
:
null
,
"tumor_code"
:
null
,
"tissue_type"
:
null
,
"days_to_sample_procurement"
:
null
,
"cases"
:
[
{
"id"
:
"11f83251-832f-4a8b-8384-a2f6256557e0"
,
"submitter_id"
:
"TCGA-ALCH-000026"
}
],
"freezing_method"
:
null
,
"type"
:
"sample"
,
"preservation_method"
:
null
,
"days_to_collection"
:
null
,
"initial_weight"
:
null
,
"longest_dimension"
:
null
}
],
"read_group"
:
[
{
"library_name"
:
"Solexa-34688"
,
"is_paired_end"
:
true
,
"size_selection_range"
:
null
,
"adapter_sequence"
:
null
,
"library_strand"
:
null
,
"submitter_id"
:
"Blood-00001-aliquot_lane1_barcode26"
,
"library_preparation_kit_name"
:
null
,
"adapter_name"
:
null
,
"target_capture_kit_name"
:
null
,
"includes_spike_ins"
:
null
,
"library_preparation_kit_version"
:
null
,
"id"
:
"90163202-cfd7-4f6a-8214-e7e4e924d3a6"
,
"spike_ins_concentration"
:
null
,
"target_capture_kit_vendor"
:
null
,
"read_length"
:
75
,
"sequencing_date"
:
"2010-08-04"
,
"spike_ins_fasta"
:
null
,
"to_trim_adapter_sequence"
:
null
,
"RIN"
:
null
,
"platform"
:
"Illumina"
,
"library_selection"
:
"Hybrid_Selection"
,
"library_strategy"
:
"WXS"
,
"library_preparation_kit_catalog_number"
:
null
,
"target_capture_kit_target_region"
:
null
,
"fastq_name"
:
null
,
"target_capture_kit_version"
:
null
,
"aliquots"
:
[
{
"id"
:
"e66dee54-5f4c-4471-9e08-dba0f6cdaaa4"
,
"submitter_id"
:
"Blood-00001-aliquot26"
}
],
"read_group_name"
:
"205DD.3-2"
,
"library_preparation_kit_vendor"
:
null
,
"project_id"
:
"TCGA-ALCH"
,
"type"
:
"read_group"
,
"target_capture_kit_catalog_number"
:
null
,
"instrument_model"
:
"Illumina HiSeq 2000"
,
"base_caller_name"
:
null
,
"experiment_name"
:
"Resequencing"
,
"flow_cell_barcode"
:
"205DDABXX"
,
"sequencing_center"
:
"BI"
1.6.8 Retrieving Entities
- 127/232 -
© 2015-2024
GraphQL
Submitters can use the GraphQL query language for advanced search and retrieval of data from the GDC Submission Portal. See
GraphQL for more information.
1.6.9 Patching Entitites
The GDC Submission API supports the HTTP PATCH method for updating existing entities with additional fields.
PATCH can be used to add extra fields to an existing entity, without requiring the submission of required fields.
The PATCH method cannot be used to create new entities, and the provided submitter_id must match an existing submitter_id.
EXAMPLE: CREATING A NEW DEMOGRAPHIC ENTITY USING POST
Request1 Command1
{
"type"
:
"demographic"
,
"submitter_id"
:
"demographic7892"
,
"cases"
:
{
"submitter_id"
:
"GDC-INTERNAL-000073"
},
"ethnicity"
:
"not reported"
,
"gender"
:
"male"
,
"race"
:
"white"
,
"vital_status"
:
"Dead"
}
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
POST
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL
Response1
{
"cases_related_to_created_entities_count"
:
1
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
201
,
"created_entity_count"
:
1
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"4e4f29a3-5325-47ef-a583-a251677ed29a"
,
"related_cases"
:
[
{
"id"
:
"71d17c1f-8985-4b2f-bb63-1c39cb6562d5"
,
"submitter_id"
:
"GDC-INTERNAL-000073"
}
],
"type"
:
"demographic"
,
"unique_keys"
:
[
{
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"demographic7892"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction successful."
,
"success"
:
true
,
"transaction_id"
:
6357750
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
1.6.9 Patching Entitites
- 128/232 -
© 2015-2024
EXAMPLE: UPDATING THE EXISTING DEMOGRAPHIC ENTITY USING PATCH
"Response2"
1.6.10 Deleting Entities
The entities endpoint can also be used to delete entities. This is accomplished using a DELETE request to the endpoint,
specifying the entity's UUID. If an entity cannot be deleted because it is linked to child entities, the GDC Submission API will
respond with an error providing a list of entities that must be deleted prior to deleting the subject entity.
A subgraph (a parent along with all of its child entities) can be deleted in a single transaction by passing a comma-separated list of
UUIDs to the entities endpoint.
Request2
{
"type"
:
"demographic"
,
"submitter_id"
:
"demographic7892"
,
"cause_of_death"
:
"Infection"
,
"cause_of_death_source"
:
"Death Certificate"
,
"country_of_birth"
:
"Antigua and Barbuda"
,
"country_of_residence_at_enrollment"
:
"Antigua and Barbuda"
}
Command2
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
PATCH
--data-binary
@Request
--header
'Content-Type: application/json'
https://api.gdc.cancer.gov/v0/submission/GDC/
INTERNAL
```json
{
"cases_related_to_created_entities_count": 0,
"cases_related_to_updated_entities_count": 1,
"code": 200,
"created_entity_count": 0,
"entities": [
{
"action": "update",
"errors": [],
"id": "4e4f29a3-5325-47ef-a583-a251677ed29a",
"related_cases": [
{
"id":"71d17c1f-8985-4b2f-bb63-1c39cb6562d5",
"submitter_id":"GDC-INTERNAL-000073"
}
],
"type": "demographic",
"unique_keys": [
{
"project_id": "GDC-INTERNAL",
"submitter_id": "demographic7892"
}
],
"valid": true,
"warnings": []
}
],
"entity_error_count": 0,
"message": "Transaction successful.",
"success": true,
"transaction_id": 6357751,
"transactional_error_count": 0,
"transactional_errors": [],
"updated_entity_count": 1
}
```
1.6.10 Deleting Entities
- 129/232 -
© 2015-2024
Entities in submitted state (assigned when the project has been submitted) cannot be deleted.
1.6.11 Working With Files
Uploading Data Files
Experimental data files like BAM and FASTQ can be uploaded directly to the API using the files endpoint, by specifying the
UUID of the corresponding data_file entity. Binary upload mode must be used if available. Uploading large files may be more
efficiently performed using the GDC Data Transfer Tool.
UPLOAD MANIFEST
The manifest endpoint generates a manifest for uploading files using the GDC Data Transfer Tool. It requires a comma-separated
list of file UUIDs to generate a manifest.
Uploading New Versions of Data Files
The GDC Submission system supports submitting updated versions of files. For example, you may want to submit an updated
version of a clinical supplement file that contains new clinical information about a patient. If a file is in file_state validated then
you would simply delete and upload a new copy of this file. No additional version of the file will be created in this case. The UUID
of the node stays the same.
However, if a file is in file_state submitted or validated and state released then a different process is required. In this situation
simply upload a new template containing updated metadata (e.g. md5sum or file_size). A new node (with a new UUID) will
automatically be created that is linked to the previous version. Once this new file is indexed and released to users they will be able
Shell Response
token
=
$(
<gdc-token-text-file.txt
)
curl
--header
"X-Auth-Token:
$token
"
--request
DELETE
https://api.gdc.cancer.gov/v0/submission/TCGA/ALCH/entities/67782964-0065-491d-b051-2ae404bb734d
{
"code"
:
200
,
"deleted_entity_count"
:
1
,
"dependent_ids"
:
""
,
"entities"
:
[
{
"action"
:
"delete"
,
"errors"
:
[],
"id"
:
"67782964-0065-491d-b051-2ae404bb734d"
,
"related_cases"
:
[],
"type"
:
"case"
,
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Successfully deleted 1 entities"
,
"success"
:
true
,
"transaction_id"
:
192
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[]
}
token=$(<gdc-token-text-file.txt)
curl --header "X-Auth-Token: $token" --output needed_to_show_progress_bar.log --request PUT --data-binary @GDC-INTERNAL-000084-S1-Q1-RG1.fastq.zip https://
api.gdc.cancer.gov/v0/submission/GDC/INTERNAL/files/c414a205-376e-4993-af48-2a4689eb433e && rm needed_to_show_progress_bar.log
# "&& rm needed_to_show_progress_bar.log" at the end of the command above
# removes the temporary file required to show upload progress bar. This
# will not work on Windows platforms. Windows users must remove this
# string and can delete the file manually.
https://api.gdc.cancer.gov/v0/submission/PROGRAM/PROJECT/manifest?ids=bf0751ca-fc3b-4760-b876-0fefce040be5,90163202-cfd7-4f6a-8214-e7e4e924d3a6
1.6.11 Working With Files
- 130/232 -
© 2015-2024
to query the new UUID in the /files endpoint and both versions' UUID in the files/versions or /history endpoint. In the example
below we register a file, upload the file, and register a new version of this file.
1.6.11 Working With Files
- 131/232 -
© 2015-2024
1.6.11 Working With Files
- 132/232 -
© 2015-2024
Request Command Response Request2 Command2 Response2
[
{
"data_type"
:
"Clinical Supplement"
,
"file_name"
:
"nationwidechildrens.org_clinical.TCGA-4G-AAZT-.xml"
,
"md5sum"
:
"ecaaa87613ba03c971bfefdb6f693959"
,
"data_format"
:
"BCR XML"
,
"submitter_id"
:
"nationwidechildrens.org_CHOL.bio.Level_1.428.25.0.tar.gz_nationwidechildrens.org_clinical.TCGA-4G-AAZT-.xml"
,
"archives"
:
[],
"data_category"
:
"Clinical"
,
"file_size"
:
39195
,
"cases"
:
[
{
"id"
:
"b10c64c2-7fd2-4210-b975-034affb14b57"
,
"submitter_id"
:
"TCGA-4G-AAZT"
}
],
"project_id"
:
"TCGA-CHOL"
,
"type"
:
"clinical_supplement"
}
]
curl
--header
"X-Auth-Token:
$token
"
--header
'Content-Type: json'
--request
PUT
--data-binary
@clin.json
'https://api.gdc.cancer.gov/submission/TCGA/CHOL'
{
"cases_related_to_created_entities_count"
:
1
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
200
,
"created_entity_count"
:
1
,
"entities"
:
[
{
"action"
:
"create"
,
"errors"
:
[],
"id"
:
"d65c15d9-9e33-4a0b-863d-605ad6155506"
,
"related_cases"
:
[
{
"id"
:
"b10c64c2-7fd2-4210-b975-034affb14b57"
,
"submitter_id"
:
"TCGA-4G-AAZT"
}
],
"type"
:
"clinical_supplement"
,
"unique_keys"
:
[
{
"project_id"
:
"TCGA-CHOL"
,
"submitter_id"
:
"nationwidechildrens.org_CHOL.bio.Level_1.428.25.0.tar.gz_nationwidechildrens.org_clinical.TCGA-4G-AAZT-.xml"
}
],
"valid"
:
true
,
"warnings"
:
[]
}
],
"entity_error_count"
:
0
,
"message"
:
"Transaction successful."
,
"success"
:
true
,
"transaction_id"
:
922606
,
"transactional_error_count"
:
0
,
"transactional_errors"
:
[],
"updated_entity_count"
:
0
}
[
{
"data_type"
:
"Clinical Supplement"
,
"file_name"
:
"nationwidechildrens.org_clinical.TCGA-4G-AAZT-.xml"
,
"md5sum"
:
"93e306e5e621d3cacb363e2be96ca3cd"
,
"data_format"
:
"BCR XML"
,
"submitter_id"
:
"nationwidechildrens.org_CHOL.bio.Level_1.428.25.0.tar.gz_nationwidechildrens.org_clinical.TCGA-4G-AAZT-.xml"
,
"archives"
:
[],
"data_category"
:
"Clinical"
,
"file_size"
:
39197
,
"cases"
:
[
{
"id"
:
"b10c64c2-7fd2-4210-b975-034affb14b57"
,
"submitter_id"
:
"TCGA-4G-AAZT"
}
],
"project_id"
:
"TCGA-CHOL"
,
"type"
:
"clinical_supplement"
}
]
curl
--header
"X-Auth-Token:
$token
"
--header
'Content-Type: json'
--request
PUT
--data-binary
@clin_v2.json
'https://api.gdc.cancer.gov/submission/TCGA/CHOL'
{
"cases_related_to_created_entities_count"
:
0
,
"cases_related_to_updated_entities_count"
:
0
,
"code"
:
200
,
"created_entity_count"
:
0
,
"entities"
:
[
{
"action"
:
"version"
,
"errors"
:
[],
"id"
:
"32e9fd2c-877a-4700-a06f-bb34e0590ca5"
,
"related_cases"
:
[
{
"id"
:
"b10c64c2-7fd2-4210-b975-034affb14b57"
,
"submitter_id"
:
"TCGA-4G-AAZT"
}
],
"type"
:
"clinical_supplement"
,
"unique_keys"
:
[
1.6.11 Working With Files
- 133/232 -
© 2015-2024
Downloading Files
Files in file_state = validated can be downloaded by the submitter using the API or the Data Transfer Tool. This is done in a
similar manner as files available in the Data Portal, but will require submission access to the particular project in dbGaP as
opposed to downloader access. File UUIDs can be found in the original upload manifest file, the submission portal, or by API calls.
See Downloading Files for details.
Deleting Files
Uploaded files must be deleted using a two step process. First, the file is deleted using the Data Transfer Tool. See Deleting
Previously Uploaded Data for details.
Second, the file node can be deleted or modified. See Deleting Entities for details.
1.6.12 Querying Submitted Data Using GraphQL
GraphQL Overview
GraphQL is a query language that makes it easy to search and retrieve data from graph data structures such as the GDC Data
Model.
Unlike the methods outlined in Search and Retrieval, which provide access to public releases (or snapshots) of GDC data, the /
graphql endpoint of GDC Submission API makes it possible for submitters to access "live" data, which provides a real-time view of
the state of entities in a project.
NOTE: Access to GDC Submission API GraphQL service is limited to authorized and authenticated submitters. Submitters may
only access data in their own project using GraphQL.
GraphQL IDE
The GDC GraphQL IDE is an instance of GraphiQL, an in-browser GraphQL IDE that facilitates construction and execution of
GraphQL queries. The GDC GraphQL IDE provides tab-completion and syntax checking using schema from the GDC Data
Dictionary. It can be found at https://portal.gdc.cancer.gov/submission/graphiql.
Before interacting directly with the GDC Submission API's GraphQL endpoint, users are encouraged to become familiar with
executing queries using the GDC GraphQL IDE.
GraphQL Endpoint
GDC data submitters can access the GDC Submission API GraphQL endpoint at:
where [API_version/] is the optional API version component (see Getting Started).
NOTE: An authentication token is required for all requests to the
graphql endpoint. Queries are restricted to those projects for
which the submitter has obtained authorization.
Constructing a Query
When sending GraphQL requests to the API directly, the bare GraphQL query must be wrapped in a "query" JSON object as shown
below:
When using the GDC GraphQL IDE, the bare JSON query must be used without a JSON wrapper.
https://api.gdc.cancer.gov/[API_version/]submission/graphql
{
"query": "{Bare_GraphQL_Query}",
"variables": null
}
1.6.12 Querying Submitted Data Using GraphQL
- 134/232 -
© 2015-2024
BARE GRAPHQL QUERY
In its simplest form, a GraphQL query is a selection set (curly brackets) that encloses a set of fields. The selection set defines the
set of information that is to be retrieved. Furthermore, in GraphQL fields are conceptually equivalent to functions that retrieve
additional fields and, in some cases, can take arguments. So each field in a selection set can have its own selection set, thereby
creating a nested query structure that can navigate complex data relationships. See GraphQL Specification for further details.
In GDC GraphQL IDE, a root field (field within the outermost/umbrella selection set) typically corresponds to an entity, whereas
fields inside nested selection sets are typically a combination of entities and entity properties.
The "Docs" panel on the right-hand side of the GDC GraphQL IDE allows users to discover the fields that can be queried with
GraphQL. Note that the panel contains a lot of information and users may experience a delay before it is displayed.
A simple GraphQL query looks like this:
The query above has two root fields:
case and _case_count . The case field corresponds to the case entity in the GDC Data Model.
The query supplies two arguments to the field:
1. project_id: "TCGA-ALCH" , which requests only cases in the TCGA-ALCH project.
2. first: 0 , which requests that the API provide all results in the response, without pagination ( a nonzero positive integer value of
first specifies the number of results to return, 10 by default; "pages" are selected using offset ).
The _case_count field is a special field that returns the number of cases that match the supplied argument.
The bare query above can be used as is in the GraphQL IDE. In order to pass this query to the GDC API directly, it needs to be
further processed as described below.
PASSING GRAPHQL QUERIES TO GDC API DIRECTLY
Before a bare GraphQL query is passed to the GDC API, it must be processed as follows:
1. Escape the query using JSON string rules
2. Wrap the query in a "query" JSON object.
3. Pass the query to the graphql endpoint in an HTTP POST request.
Using the case and _case_count example above as the starting point, the results are as follows:
{
case (project_id: "TCGA-ALCH", first: 0) {
id
submitter_id
}
_case_count (project_id: "TCGA-ALCH")
}
1.6.12 Querying Submitted Data Using GraphQL
- 135/232 -
© 2015-2024
1.6.12 Querying Submitted Data Using GraphQL
- 136/232 -
© 2015-2024
bare_GraphQL escaped_GraphQL Query_json Shell_command API_Response
{
case
(
project_id
:
"TCGA-ALCH"
,
first
:
0
)
{
id
submitter_id
}
_case_count
(
project_id
:
"TCGA-ALCH"
)
}
{
\
n
\
tcase
(
project_id
:
\
"TCGA-ALCH
\"
, first: 0) {
\n\t\t
id
\n\t\t
submitter_id
\n\n\t
}
\n\t
_case_count (project_id:
\"
TCGA-ALCH
\"
)
\n
}
{
"query"
:
"{\n\tcase (project_id: \"TCGA-ALCH\", first: 0) {\n\t\tid\n\t\tsubmitter_id\n\n\t}\n\t_case_count (project_id: \"TCGA-ALCH\")\n}"
,
"variables"
:
null
}
token
=
$(
<gdc-token-text-file.txt
)
curl
--request
POST
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/v0/submission/graphql'
--data-binary
@Query_json
{
"data"
:
{
"_case_count"
:
20
,
"case"
:
[
{
"id"
:
"700d1110-b6b4-4251-89d4-fa6f0698e3f8"
,
"submitter_id"
:
"TCGA-ALCH-000004"
},
{
"id"
:
"be01357d-7348-40b4-a997-8a61ae7af17d"
,
"submitter_id"
:
"TCGA-ALCH-000005"
},
{
"id"
:
"e5638697-6ef3-4bf8-a373-102519093f33"
,
"submitter_id"
:
"TCGA-ALCH-000008"
},
{
"id"
:
"4871d41a-680e-4fd0-901c-b06f06ecae33"
,
"submitter_id"
:
"TCGA-ALCH-000007"
},
{
"id"
:
"2f18c2c1-bff2-43b6-9702-e138c72d8c6b"
,
"submitter_id"
:
"TCGA-ALCH-000009"
},
{
"id"
:
"ec83e038-4f01-47a6-bc69-47fb297d0282"
,
"submitter_id"
:
"TCGA-ALCH-000006"
},
{
"id"
:
"e4642952-d259-4be1-9c53-ed95aa1fc50b"
,
"submitter_id"
:
"TCGA-ALCH-000011"
},
{
"id"
:
"8bcaf0b3-21d0-45c6-87ee-c997efb417dc"
,
"submitter_id"
:
"TCGA-ALCH-000010"
},
{
"id"
:
"83de027e-bcbf-4239-975b-7e8ced82448e"
,
"submitter_id"
:
"TCGA-ALCH-000013"
},
{
"id"
:
"bbd91cc1-06e2-4e60-8b93-e09c3b16f00c"
,
"submitter_id"
:
"TCGA-ALCH-000014"
},
{
"id"
:
"574fd163-4368-440c-9548-d76a0fbc9056"
,
"submitter_id"
:
"TCGA-ALCH-000015"
},
{
"id"
:
"47c92cdd-ff11-4c25-b0f0-0f7671144271"
,
"submitter_id"
:
"TCGA-ALCH-000016"
},
{
"id"
:
"9f13caab-1fda-4b2a-b500-f79dc978c6c1"
,
"submitter_id"
:
"TCGA-ALCH-000017"
},
{
"id"
:
"9418f194-8741-44db-bd8f-36f4fd8c3bf2"
,
"submitter_id"
:
"TCGA-ALCH-000018"
},
{
"id"
:
"6fb2a018-c5f3-45e5-81d3-e58e7e4bf921"
,
"submitter_id"
:
"TCGA-ALCH-000019"
},
{
"id"
:
"70236972-e796-414a-9b7a-3b29b849ba7c"
,
"submitter_id"
:
"TCGA-ALCH-000020"
},
{
"id"
:
"6f78e86f-9e31-4af5-a0d9-b8970ece476d"
,
"submitter_id"
:
"TCGA-ALCH-000021"
},
{
"id"
:
"c6fcb2f0-c6bb-4b40-a761-bae3e63869cb"
,
"submitter_id"
:
"TCGA-ALCH-000002"
},
{
"id"
:
"67782964-0065-491d-b051-2ae404bb734d"
,
"submitter_id"
:
"TCGA-ALCH-000001"
},
{
1.6.12 Querying Submitted Data Using GraphQL
- 137/232 -
© 2015-2024
Additional Examples
EXAMPLE: FILE UUID
GraphQL query to find the file UUID based on file submitter_id :
EXAMPLE: CASE WITHOUT DIAGNOSIS
GraphQL query for any one case in 'TCGA-LUAD' without Diagnosis information:
bare_GraphQL escaped_GraphQL Shell Response
{
submitted_unaligned_reads
(
project_id
:
"GDC-INTERNAL"
,
submitter_id
:
"Blood-00001-aliquot_lane1_barcode23.fastq"
)
{
id
submitter_id
file_name
project_id
}
}
{
"
query
":
"
{
\
n
\
n
submitted_unaligned_reads
(
project_id
:
\
"GDC-INTERNAL
\"
, submitter_id:
\"
Blood-00001-aliquot_lane1_barcode23.fastq
\"
) {
\n
id
\n
submitter_id
\n
file_name
\n
project_id
\n
}
\n
}"
,
"
variables
"
:
null
}
curl
--request
POST
--header
"X-Auth-Token:
$token
"
'https://api.gdc.cancer.gov/v0/submission/graphql'
--data-binary
@escaped_GraphQL
{
"data"
:
{
"submitted_unaligned_reads"
:
[
{
"file_name"
:
"dummy.fastq"
,
"id"
:
"616eab2f-791a-4641-8cd6-ee195a10a201"
,
"project_id"
:
"GDC-INTERNAL"
,
"submitter_id"
:
"Blood-00001-aliquot_lane1_barcode23.fastq"
}
]
}
}
bare_GraphQL Response
{
case
(
project_id
:
"TCGA-LUAD"
,
without_links
:
[
"diagnoses"
],
first
:
1
)
{
submitter_id
}
}
{
"data"
:
{
"case"
:
[
{
"submitter_id"
:
"TCGA-17-Z050"
}
]
}
}
1.6.12 Querying Submitted Data Using GraphQL
- 138/232 -
© 2015-2024
EXAMPLE: NUMBER OF CASES WITHOUT DIAGNOSIS
GraphQL query for the number of cases in 'TCGA-LUAD' without Diagnosis information:
EXAMPLE: ALIQUOT STATE
Query for the state of aliquots belonging to case with submitter_id: "TCGA-ALCH-000001" :
EXAMPLE: ALIASES
GraphQL query that uses a GraphQL fragment to get specific properties from two portions and give them aliases in the response:
bare_GraphQL Response
{
_case_count
(
project_id
:
"TCGA-LUAD"
,
without_links
:
[
"diagnoses"
])
}
{
"data"
:
{
"_case_count"
:
5
}
}
bare_GraphQL Response
{
aliquot
(
with_path_to
:
{
type
:
"case"
,
submitter_id
:
"TCGA-ALCH-000001"
})
{
id
release_state
}
}
{
"data"
:
{
"aliquot"
:
[
{
"id"
:
"7af58da0-cb3e-43e2-a074-4bd8f27565ba"
,
"state"
:
"validated"
}
]
}
}
bare_GraphQL Response
{
some_portion
:
portion
(
first
:
1
)
{
...
portionProperties
}
specific_portion
:
portion
(
submitter_id
:
"TCGA-67-6217-01A-13-2191-20"
)
{
...
portionProperties
}
}
fragment
portionProperties
on
portion
{
submitter_id
is_ffpe
}
{
"data"
:
{
"some_portion"
:
[
{
"is_ffpe"
:
false
,
"submitter_id"
:
"TCGA-62-A471-10A-01"
}
],
"specific_portion"
:
[
{
"is_ffpe"
:
false
,
"submitter_id"
:
"TCGA-67-6217-01A-13-2191-20"
}
]
}
}
1.6.12 Querying Submitted Data Using GraphQL
- 139/232 -
© 2015-2024
EXAMPLE: BIOSPECIMEN TREE
GraphQL Query for a case in "TCGA-LUAD" and return a biospecimen tree:
bare_GraphQL Response
{
case
(
project_id
:
"TCGA-LUAD"
,
first
:
1
)
{
id
samples
(
first
:
1
)
{
id
portions
(
first
:
1
)
{
id
analytes
(
first
:
1
)
{
id
aliquots
(
first
:
1
)
{
id
}
}
}
}
}
}
{
"data"
:
{
"case"
:
[
{
"id"
:
"19ca36e6-2154-4224-89b1-117a4a4407f6"
,
"samples"
:
[
{
"id"
:
"5e2625d2-290d-48cd-af5c-27dc8e3c8b6a"
,
"portions"
:
[
{
"analytes"
:
[
{
"aliquots"
:
[
{
"id"
:
"8e1820d5-dcd8-4760-9962-221e2b71d4b9"
}
],
"id"
:
"6449533c-e52a-4e58-bae7-0732f48153ef"
}
],
"id"
:
"26b75643-8fcd-445e-a0e0-9868cac589ea"
}
]
}
]
}
]
}
}
1.6.12 Querying Submitted Data Using GraphQL
- 140/232 -
© 2015-2024
1.7 Using Python to Query the GDC API
Python can be a versatile tool for retrieving information from the GDC API and performing downstream processing. This page
details some examples that demonstrate the basic API queries using Python. The examples in this guide will use the requests
Python library and should be compatible with Python3.
1.7.1 Querying Metadata
Python can be used with the GDC API to retrieve metadata that is indexed in the GDC Database. See the Search and Retrieval
section of the API documentation for specific details about parameters and usage.
A Basic Query
This example passes some basic parameters (fields, format, size) to the cases endpoint and prints the results in a tab-delimited
format. Note that the fields parameter needs to be a string comprising comma-delimited field names.
Download Script
A Filtered Query
In the next example, a filters parameter is added to the script. This parameter is passed as a Python dictionary object. The filter
used in this example will only display cases that come from a kidney disease study ( primary_site: Kidney ).
import
requests
import
json
cases_endpt
=
'https://api.gdc.cancer.gov/cases'
# The 'fields' parameter is passed as a comma-separated string of single names.
fields
=
[
"submitter_id"
,
"case_id"
,
"primary_site"
,
"disease_type"
,
"diagnoses.vital_status"
]
fields
=
','
.
join
(
fields
)
params
=
{
"fields"
:
fields
,
"format"
:
"TSV"
,
"size"
:
"100"
}
response
=
requests
.
get
(
cases_endpt
,
params
=
params
)
print
(
response
.
content
)
import
requests
import
json
fields
=
[
"submitter_id"
,
"case_id"
,
"primary_site"
,
"disease_type"
,
"diagnoses.vital_status"
]
fields
=
","
.
join
(
fields
)
cases_endpt
=
"https://api.gdc.cancer.gov/cases"
filters
=
{
"op"
:
"in"
,
"content"
:{
"field"
:
"primary_site"
,
"value"
:
[
"Kidney"
]
}
}
# With a GET request, the filters parameter needs to be converted
# from a dictionary to JSON-formatted string
params
=
{
1.7 Using Python to Query the GDC API
- 141/232 -
© 2015-2024
Download Script
Complex Filters
The following example uses the and operator in the filter to returns information about files that 1) were produced using RNA-Seq,
2) are downloadable in BAM format, and 3) originate from lung cancer patients. Note that these three filters are nested within a
list in the highest level content key.
Download Script
1.7.2 Downloading Files
GDC files can also be downloaded from the API and saved locally using Python scripts. See the File Download section of the API
documentation for more information.
"filters"
:
json
.
dumps
(
filters
),
"fields"
:
fields
,
"format"
:
"TSV"
,
"size"
:
"100"
}
response
=
requests
.
get
(
cases_endpt
,
params
=
params
)
print
(
response
.
content
)
import
requests
import
json
fields
=
[
"file_name"
,
"cases.submitter_id"
,
"cases.samples.sample_type"
,
"cases.disease_type"
,
"cases.project.project_id"
]
fields
=
","
.
join
(
fields
)
files_endpt
=
"https://api.gdc.cancer.gov/files"
# This set of filters is nested under an 'and' operator.
filters
=
{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"in"
,
"content"
:{
"field"
:
"cases.project.primary_site"
,
"value"
:
[
"Lung"
]
}
},
{
"op"
:
"in"
,
"content"
:{
"field"
:
"files.experimental_strategy"
,
"value"
:
[
"RNA-Seq"
]
}
},
{
"op"
:
"in"
,
"content"
:{
"field"
:
"files.data_format"
,
"value"
:
[
"BAM"
]
}
}
]
}
# A POST is used, so the filter parameters can be passed directly as a Dict object.
params
=
{
"filters"
:
filters
,
"fields"
:
fields
,
"format"
:
"TSV"
,
"size"
:
"2000"
}
# The parameters are passed to 'json' rather than 'params' in this case
response
=
requests
.
post
(
files_endpt
,
headers
=
{
"Content-Type"
:
"application/json"
},
json
=
params
)
print
(
response
.
content
.
decode
(
"utf-8"
))
1.7.2 Downloading Files
- 142/232 -
© 2015-2024
A Simple Download Request
An open-access GDC file can be downloaded by appending the file UUID to the data endpoint URL.
Download Script
Passing a Token to Download a Controlled-Access File
A token can be passed to the script by specifying a plain text file that contains only the GDC token. A token can be downloaded by
logging into the GDC Data Portal. See the Data Security documentation for more details.
Download Script
Post Request to Download Multiple Files
This example uses a Python list to specify a set of file UUIDs. The list in the example was populated manually but could potentially
be populated programmatically from an external list or API call.
import
requests
import
json
import
re
file_id
=
"b658d635-258a-4f6f-8377-767a43771fe4"
data_endpt
=
"https://api.gdc.cancer.gov/data/
{}
"
.
format
(
file_id
)
response
=
requests
.
get
(
data_endpt
,
headers
=
{
"Content-Type"
:
"application/json"
})
# The file name can be found in the header within the Content-Disposition key.
response_head_cd
=
response
.
headers
[
"Content-Disposition"
]
file_name
=
re
.
findall
(
"filename=(.+)"
,
response_head_cd
)[
0
]
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
import
requests
import
json
'''
This script will not work until $TOKEN_FILE_PATH
is replaced with an actual path.
'''
token_file
=
"$TOKEN_FILE_PATH"
file_id
=
"11443f3c-9b8b-4e47-b5b7-529468fec098"
data_endpt
=
"https://api.gdc.cancer.gov/slicing/view/
{}
"
.
format
(
file_id
)
with
open
(
token_file
,
"r"
)
as
token
:
token_string
=
str
(
token
.
read
()
.
strip
())
params
=
{
"gencode"
:
[
"BRCA1"
,
"BRCA2"
]}
response
=
requests
.
post
(
data_endpt
,
data
=
json
.
dumps
(
params
),
headers
=
{
"Content-Type"
:
"application/json"
,
"X-Auth-Token"
:
token_string
})
file_name
=
"brca_slices.bam"
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
import
requests
import
json
import
re
data_endpt
=
"https://api.gdc.cancer.gov/data"
ids
=
[
"b658d635-258a-4f6f-8377-767a43771fe4"
,
"3968213d-b293-4b3d-8033-5b5a0ca07b6c"
]
params
=
{
"ids"
:
ids
}
response
=
requests
.
post
(
data_endpt
,
1.7.2 Downloading Files
- 143/232 -
© 2015-2024
Download Script
Downloading a Set of Files Based on a Filter
Here a list of files based on a set of filters are downloaded. File UUIDs are retrieved based on the filters. These UUIDs are then
passed to the data endpoint to download the correct files.
data
=
json
.
dumps
(
params
),
headers
=
{
"Content-Type"
:
"application/json"
})
response_head_cd
=
response
.
headers
[
"Content-Disposition"
]
file_name
=
re
.
findall
(
"filename=(.+)"
,
response_head_cd
)[
0
]
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
import
requests
import
json
import
re
files_endpt
=
"https://api.gdc.cancer.gov/files"
filters
=
{
"op"
:
"and"
,
"content"
:[
{
"op"
:
"in"
,
"content"
:{
"field"
:
"cases.project.primary_site"
,
"value"
:
[
"Lung"
]
}
},
{
"op"
:
"in"
,
"content"
:{
"field"
:
"cases.demographic.race"
,
"value"
:
[
"white"
]
}
},
{
"op"
:
"in"
,
"content"
:{
"field"
:
"cases.demographic.gender"
,
"value"
:
[
"female"
]
}
},
{
"op"
:
"in"
,
"content"
:{
"field"
:
"files.analysis.workflow_type"
,
"value"
:
[
"HTSeq - FPKM"
]
}
}
]
}
# Here a GET is used, so the filter parameters should be passed as a JSON string.
params
=
{
"filters"
:
json
.
dumps
(
filters
),
"fields"
:
"file_id"
,
"format"
:
"JSON"
,
"size"
:
"1000"
}
response
=
requests
.
get
(
files_endpt
,
params
=
params
)
file_uuid_list
=
[]
# This step populates the download list with the file_ids from the previous query
for
file_entry
in
json
.
loads
(
response
.
content
.
decode
(
"utf-8"
))[
"data"
][
"hits"
]:
file_uuid_list
.
append
(
file_entry
[
"file_id"
])
data_endpt
=
"https://api.gdc.cancer.gov/data"
params
=
{
"ids"
:
file_uuid_list
}
response
=
requests
.
post
(
data_endpt
,
data
=
json
.
dumps
(
params
),
headers
=
{
"Content-Type"
:
"application/json"
})
response_head_cd
=
response
.
headers
[
"Content-Disposition"
]
file_name
=
re
.
findall
(
"filename=(.+)"
,
response_head_cd
)[
0
]
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
1.7.2 Downloading Files
- 144/232 -
© 2015-2024
Download Script
BAM Slicing
The GDC BAM Slicing feature can also be accessed through Python. Below is an example of a basic BAM slicing command.
Download Script
The same region(s) across multiple BAM files can be retrieved using a for-loop within a Python script.
Download Script
import
requests
import
json
'''
This script will not work until $TOKEN_FILE_PATH
is replaced with an actual path.
'''
token_file
=
"$TOKEN_FILE_PATH"
file_id
=
"11443f3c-9b8b-4e47-b5b7-529468fec098"
data_endpt
=
"https://api.gdc.cancer.gov/slicing/view/
{}
"
.
format
(
file_id
)
with
open
(
token_file
,
"r"
)
as
token
:
token_string
=
str
(
token
.
read
()
.
strip
())
params
=
{
"gencode"
:
[
"BRCA1"
,
"BRCA2"
]}
response
=
requests
.
post
(
data_endpt
,
data
=
json
.
dumps
(
params
),
headers
=
{
"Content-Type"
:
"application/json"
,
"X-Auth-Token"
:
token_string
})
file_name
=
"brca_slices.bam"
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
import
requests
import
json
'''
This script will not work until $TOKEN_FILE_PATH
is replaced with an actual path.
'''
token_file
=
"$TOKEN_FILE_PATH"
file_ids
=
[
"11443f3c-9b8b-4e47-b5b7-529468fec098"
,
"1f103620-bb34-46f1-b565-94f0027e396d"
,
"ca549554-a244-4209-9086-92add7bb7109"
]
for
file_id
in
file_ids
:
data_endpt
=
"https://api.gdc.cancer.gov/slicing/view/
{}
"
.
format
(
file_id
)
with
open
(
token_file
,
"r"
)
as
token
:
token_string
=
str
(
token
.
read
()
.
strip
())
params
=
{
"regions"
:
[
"chr1:1-20000"
,
"chr10:129000-160000"
]
}
response
=
requests
.
post
(
data_endpt
,
data
=
json
.
dumps
(
params
),
headers
=
{
"Content-Type"
:
"application/json"
,
"X-Auth-Token"
:
token_string
})
file_name
=
"
{}
_region_slices.bam"
.
format
(
file_id
)
with
open
(
file_name
,
"wb"
)
as
output_file
:
output_file
.
write
(
response
.
content
)
1.7.2 Downloading Files
- 145/232 -
© 2015-2024
1.7.3 Basic Troubleshooting
The following script should produce an unformatted JSON string with information about the API status. Run this script to verify
that a valid connection is being made to the GDC API.
Download Script
import
requests
status_endpt
=
"https://api.gdc.cancer.gov/status"
response
=
requests
.
get
(
status_endpt
)
# OUTPUT METHOD 1: Write to a file.
file
=
open
(
"api_status.json"
,
"w"
)
file
.
write
(
response
.
text
)
file
.
close
()
# OUTPUT METHOD 2: View on screen.
print
(
response
.
content
)
1.7.3 Basic Troubleshooting
- 146/232 -
© 2015-2024
1.8 Introduction to GDC GraphQL
GraphQL is a query language for APIs. The GDC REST API has structured and specifically defined query parameters as well as
endpoints that have set requests and responses. The GDC GraphQL provides advanced GDC users greater flexibility to specify the
data they would like to be returned. This allows queries to be cleaner and easier to understand, especially when combining
multiple queries into one request.
To produce queries in a visual interface, the GDC recommends using GraphiQL. See below for the correct endpoint URLs.
1.8.1 Using GDC GraphQL vs GDC REST API
If the query requires only a subset of the data to be returned, GDC GraphQL may speed up requests as GraphQL queries return
only the specified data. This may require less work on the GDC server-side to fulfill those requests. Conversely, if an entire data-set
is required for each request, the GDC REST API may be a better fit. No matter which method is used, the data returned by the
GDC REST API and the GraphQL query will be identical as they query the same source.
1.8.2 GDC GraphQL Overview
GraphQL is not a storage model or a database query language. The graph refers to graph structures defined in the schema, where
nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the
schema definitions, independent of how the data is stored.
1.8.3 GDC GraphQL Endpoints
The GDC GraphQL has only two endpoints: * GDC Search and Retrieval Endpoint: https://api.gdc.cancer.gov/v0/graphql *
GDC Submission Endpoint: https://api.gdc.cancer.gov/v0/submission/graphql
This page covers the search and retrieval endpoint, see the GDC Submission API for additional details on the submission endpoint.
1.8.4 GDC GraphQL Schema
All GDC GraphQL queries are validated and executed against the GDC GraphQL schema. Because the GraphQL parameters are
discoverable, the GDC GraphQL schema can be queried for details about itself.
The __schema keyword can be queried to list all types defined in the schema and retrieve details about each:
GraphQL
{
__schema
{
types
{
name
kind
fields
{
name
}
}
}
}
1.8 Introduction to GDC GraphQL
- 147/232 -
© 2015-2024
The __type keyword can also be queried to retrieve details about any type such as "Explore" or "Case":
1.8.5 Basic GraphQL queries in GDC
The two types of allowed operations in GDC GraphQL API are queries and mutations. Comparing GraphQL to REST, queries
operate like GET requests, while mutations operate like POST / PATCH / DELETE .
Note: This guide does not cover GDC GraphQL mutation operations.
GraphQL queries return only the data that is specified. Queries are built by specifying fields within fields (also called nested
subfields
) until only scalars are returned. Scalars are primitive values such as: Int , Float , String , Boolean , or ID .
Explore Case
{
__type
(
name
:
"Explore"
)
{
name
kind
description
fields
{
name
}
}
}
{
__type
(
name
:
"Case"
)
{
name
kind
description
fields
{
name
}
}
}
1.8.5 Basic GraphQL queries in GDC
- 148/232 -
© 2015-2024
1.8.6 Anatomy of a typical GDC GraphQL Query
• Operation type: Describes what type of operation that is being performed, such as query, mutation, or subscription
• Operation name: Similar to a function name, gives queries meaningful names
• Field: Denotes the specific fields on objects that will be included with the response data
• Arguments: A set of key-value pairs associated with a specific field. The parameters can be literal values or variables. NOTE:
Arguments can appear on any field, even fields nested deep in an operation.
• Variable definitions: As GraphQL is strong typed, it validates the variable being passed dynamically. NOTE: Variables are
passed separately from the query document as JSON such as:
1.8.7 GDC GraphQL Examples
Nodes And Edges Example
A very powerful feature of GDC GraphQL API is that the graph structures defined in the GDC GraphQL schema can be queried
and traversed. In these queries, nodes define objects and edges define relationships between objects.
{
"filters_1"
:
{
"op"
:
"in"
,
"content"
:{
"field"
:
"projects.program.name"
,
"value"
:[
"TARGET"
]}}}
GraphQL
query
PROJECTS_EDGES
(
$filters_1
:
FiltersArgument
)
{
projects
{
hits
(
filters
:
$filters_1
)
{
total
edges
{
node
{
primary_site
disease_type
project_id
dbgap_accession_number
}
}
}
}
}
variable:
{
"
filters_1
":
{
"
op
":
"
in
"
,
"
content
":
{
"
field
":
"
projects
.
primary_site
"
,
"
value
":
["
Kidney
"]
}}}
1.8.6 Anatomy of a typical GDC GraphQL Query
- 149/232 -
© 2015-2024
Query Case File Counts
Query Simple Static Mutations Based on Gene IDs
GraphQL
query
CaseFileCounts
(
$filters
:
FiltersArgument
)
{
viewer
{
repository
{
cases
{
hits
(
first
:
1
,
filters
:
$filters
)
{
edges
{
node
{
case_id
files
{
hits
(
first
:
0
)
{
total
}
}
summary
{
experimental_strategies
{
experimental_strategy
file_count
}
data_categories
{
data_category
file_count
}
}
}
}
}
}
}
}
}
variable:
{
"
filters
":
{
"
op
":"
in
"
,
"
content
":
{
"
field
":"
cases
.
case_id
"
,
"
value
":["
dcd5860c
-7
e3a
-44
f3
-
a732
-
fe92fe3fe300
"]
}}}
GraphQL
query
PROJECTS_EDGES
(
$filters_2
:
FiltersArgument
)
{
explore
{
ssms
{
hits
(
filters
:
$filters_2
)
{
total
edges
{
node
{
ssm_id
gene_aa_change
}
}
}
}
}
}
variable:
{
"
filters_2
":
{
"
op
":"
in
"
,
"
content
":
{
"
field
":"
consequence
.
transcript
.
gene
.
gene_id
"
,
"
value
":["
ENSG00000155657
"]
}}}
1.8.7 GDC GraphQL Examples
- 150/232 -
© 2015-2024
1.9 System Information
1.9.1 Overview
The GDC API offers endpoints that provide information about the system. These endpoints are described below.
1.9.2 GDC Notifications Endpoint
The notifications endpoint provides current user-facing notifications.
GDC notifications have a corresponding level with the following meanings:
Notifications will indicate the GDC components to which they apply:
Sample Request
1.9.3 API Status Endpoint
The status endpoint provides information about the current status and version of the GDC API.
Level Meaning
INFO Non-essential information, e.g. regarding a new dataset
WARNING Important user information, e.g. regarding a dataset to be removed
ERROR Important system information, e.g. regarding a GDC component
DEBUG Unimportant system information, e.g. testing the notification system
Component Description
PORTAL The GDC Data Portal
SUBMISSION The GDC Data Submission Portal
DOCUMENTATION The GDC documentation site that contains GDC user guides, release notes, and the GDC Data
Dictionary
WEBSITE The GDC project website that includes information about the system. This does not include any of the
above-listed GDC components.
Shell Response
curl
--request
GET
https://api.gdc.cancer.gov/v0/notifications
{
"data"
:
[
{
"level"
:
"INFO"
,
"components"
:
[
"SUBMISSION_API"
"LEGACY_API"
],
"message"
:
"The system is up!"
}
]
}
1.9 System Information
- 151/232 -
© 2015-2024
Sample Request
Shell Python Response
curl
https://api.gdc.cancer.gov/status
import
requests
import
json
status_endpt
=
response
=
requests
.
get
(
status_endpt
)
print
json
.
dumps
(
response
.
json
(),
indent
=
2
)
{
"commit"
:
"74e1e3583c0f39fbf2149322addb7378206be3b9"
,
"status"
:
"OK"
,
"tag"
:
"1.2.0"
,
"version"
:
1
}
1.9.3 API Status Endpoint
- 152/232 -
© 2015-2024
1.10 Additional Examples
1.10.1 Data Search and Retrieval
Endpoint Examples
This section contains additional examples for using endpoints.
PROJECT ENDPOINT EXAMPLE
This example is a query for Projects contained in GDC. It returns only the first five projects sorted by project name.
Query Response
curl
'https://api.gdc.cancer.gov/projects?from=0&size=5&sort=project.name:asc&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"state"
:
"legacy"
,
"project_id"
:
"TARGET-AML"
,
"primary_site"
:
"Blood"
,
"disease_type"
:
"Acute Myeloid Leukemia"
,
"name"
:
"Acute Myeloid Leukemia"
},
{
"state"
:
"legacy"
,
"project_id"
:
"TCGA-LAML"
,
"primary_site"
:
"Blood"
,
"disease_type"
:
"Acute Myeloid Leukemia"
,
"name"
:
"Acute Myeloid Leukemia"
},
{
"state"
:
"legacy"
,
"project_id"
:
"TARGET-AML-IF"
,
"primary_site"
:
"Blood"
,
"disease_type"
:
"Acute Myeloid Leukemia Induction Failure"
,
"name"
:
"Acute Myeloid Leukemia Induction Failure"
},
{
"state"
:
"legacy"
,
"project_id"
:
"TARGET-ALL-P2"
,
"primary_site"
:
"Blood"
,
"disease_type"
:
"Acute Lymphoblastic Leukemia"
,
"name"
:
"Acute Lymphoblastic Leukemia - Phase II"
},
{
"state"
:
"legacy"
,
"project_id"
:
"TARGET-ALL-P1"
,
"primary_site"
:
"Blood"
,
"disease_type"
:
"Acute Lymphoblastic Leukemia"
,
"name"
:
"Acute Lymphoblastic Leukemia - Phase I"
}
],
"pagination"
:
{
"count"
:
5
,
"sort"
:
"project.name:asc"
,
"from"
:
0
,
"pages"
:
10
,
"total"
:
46
,
"page"
:
1
,
"size"
:
5
}
},
"warnings"
:
{}
}
1.10 Additional Examples
- 153/232 -
© 2015-2024
FILES ENDPOINT EXAMPLE
This example is a query for files contained in GDC. It returns only the first two files, sorted by file size, from smallest to largest.
Query Response
curl
'https://api.gdc.cancer.gov/files?from=0&size=2&sort=file_size:asc&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"data_type"
:
"Raw Simple Somatic Mutation"
,
"updated_datetime"
:
"2017-03-04T16:45:40.925270-06:00"
,
"file_name"
:
"9f78a291-2d50-472c-8f56-5f8fbd09ab2a.snp.Somatic.hc.vcf.gz"
,
"submitter_id"
:
"TCGA-13-0757-01A-01W-0371-08_TCGA-13-0757-10A-01W-0371-08_varscan"
,
"file_id"
:
"9f78a291-2d50-472c-8f56-5f8fbd09ab2a"
,
"file_size"
:
1120
,
"id"
:
"9f78a291-2d50-472c-8f56-5f8fbd09ab2a"
,
"created_datetime"
:
"2016-05-04T14:50:54.560567-05:00"
,
"md5sum"
:
"13c1ceb3519615e2c67128b350365fbf"
,
"data_format"
:
"VCF"
,
"acl"
:
[
"phs000178"
],
"access"
:
"controlled"
,
"state"
:
"live"
,
"data_category"
:
"Simple Nucleotide Variation"
,
"type"
:
"simple_somatic_mutation"
,
"file_state"
:
"submitted"
,
"experimental_strategy"
:
"WXS"
},
{
"data_type"
:
"Raw Simple Somatic Mutation"
,
"updated_datetime"
:
"2017-03-04T16:45:40.925270-06:00"
,
"file_name"
:
"7780009b-abb6-460b-903d-accdac626c2e.snp.Somatic.hc.vcf.gz"
,
"submitter_id"
:
"TCGA-HC-8261-01A-11D-2260-08_TCGA-HC-8261-10A-01D-2260-08_varscan"
,
"file_id"
:
"7780009b-abb6-460b-903d-accdac626c2e"
,
"file_size"
:
1237
,
"id"
:
"7780009b-abb6-460b-903d-accdac626c2e"
,
"created_datetime"
:
"2016-05-08T13:54:38.369393-05:00"
,
"md5sum"
:
"fd9bb46c8022b96af730c48dc00e2c41"
,
"data_format"
:
"VCF"
,
"acl"
:
[
"phs000178"
],
"access"
:
"controlled"
,
"state"
:
"live"
,
"data_category"
:
"Simple Nucleotide Variation"
,
"type"
:
"simple_somatic_mutation"
,
"file_state"
:
"submitted"
,
"experimental_strategy"
:
"WXS"
}
],
"pagination"
:
{
"count"
:
2
,
"sort"
:
"file_size:asc"
,
"from"
:
0
,
"page"
:
1
,
"total"
:
274724
,
"pages"
:
137362
,
"size"
:
2
}
},
"warnings"
:
{}
}
1.10.1 Data Search and Retrieval
- 154/232 -
© 2015-2024
CASES ENDPOINT EXAMPLE
This example is a query for cases contained in GDC. It returns only the first five files.
1.10.1 Data Search and Retrieval
- 155/232 -
© 2015-2024
1.10.1 Data Search and Retrieval
- 156/232 -
© 2015-2024
Query Response
curl
'https://api.gdc.cancer.gov/cases?from=0&size=5&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"updated_datetime"
:
"2017-03-09T10:01:14.834935-06:00"
,
"submitter_analyte_ids"
:
[
"TCGA-ER-A193-06A-12D"
,
"TCGA-ER-A193-06A-12R"
,
"TCGA-ER-A193-06A-12W"
,
"TCGA-ER-A193-10A-01W"
,
"TCGA-ER-A193-10A-01D"
],
"analyte_ids"
:
[
"62e14ca4-95f5-4af3-848f-83f7273c3b70"
,
"6178b8aa-6afb-4951-bc92-bf9bfc57b9c7"
,
"e16b701c-7809-4fb5-a9e0-4ff71e5d1d84"
,
"5bfa8c9f-6797-4b2b-9122-854f8ab3bbba"
,
"9b73d64e-c973-45b6-be31-a486fb8d1708"
],
"submitter_id"
:
"TCGA-ER-A193"
,
"case_id"
:
"8ab09143-daf6-40a9-85d3-0fe9de7b3e06"
,
"id"
:
"8ab09143-daf6-40a9-85d3-0fe9de7b3e06"
,
"disease_type"
:
"Skin Cutaneous Melanoma"
,
"sample_ids"
:
[
"378b3d8a-adbb-4912-a0bf-6b74a282113e"
,
"7a384d44-8b05-4197-9921-7d020ada2437"
],
"portion_ids"
:
[
"6680bbf2-9cf1-4f93-9ec3-04318cffb5ba"
,
"690d3b12-a61d-42fd-af2a-5a7a9a3e5de8"
,
"824d724e-6836-423e-a751-fee3260ef4d2"
],
"submitter_portion_ids"
:
[
"TCGA-ER-A193-06A-21-A20N-20"
,
"TCGA-ER-A193-10A-01"
,
"TCGA-ER-A193-06A-12"
],
"created_datetime"
:
null
,
"slide_ids"
:
[
"d2751354-a8b7-4f7a-a4f1-d062de5ceb14"
],
"state"
:
"live"
,
"aliquot_ids"
:
[
"dc9f9544-6c76-4b45-b5c3-dd2fecd5acfe"
,
"390b3574-ba23-4ecb-acf8-f5ad8a958bd2"
,
"33f43961-b32d-46fc-ba11-264f1101e78d"
,
"cd17367c-3270-42ae-8ac5-941a3453ea33"
,
"b17269a2-79aa-459e-9c3d-589b7efe6fd9"
,
"28a7d729-7555-4545-924b-3dec49b54230"
,
"13256e77-0b0b-49e3-9959-3b6730d68732"
,
"87ca642a-dd4c-47ea-b81f-2d3402f2157a"
,
"8a1bfe0e-c97a-41c4-815f-cf5bb5cfc69f"
,
"5e1e9c82-99fd-49de-9dfb-a349d4d8ac94"
,
"67f00459-e423-4900-be23-9283b0478620"
,
"d939c477-a01f-4d54-bcfb-c9fdd957f2ec"
],
"primary_site"
:
"Skin"
,
"submitter_aliquot_ids"
:
[
"TCGA-ER-A193-06A-12D-A18Y-02"
,
"TCGA-ER-A193-10A-01D-A193-01"
,
"TCGA-ER-A193-10A-01D-A190-02"
,
"TCGA-ER-A193-06A-12D-A197-08"
,
"TCGA-ER-A193-06A-12R-A18S-07"
,
"TCGA-ER-A193-06A-12W-A20H-08"
,
"TCGA-ER-A193-10A-01D-A199-08"
,
"TCGA-ER-A193-10A-01D-A38R-08"
,
"TCGA-ER-A193-10A-01W-A20J-08"
,
"TCGA-ER-A193-06A-12R-A18V-13"
,
"TCGA-ER-A193-06A-12D-A19C-05"
,
"TCGA-ER-A193-06A-12D-A191-01"
],
"submitter_sample_ids"
:
[
"TCGA-ER-A193-10A"
,
"TCGA-ER-A193-06A"
],
"submitter_slide_ids"
:
[
"TCGA-ER-A193-06A-01-TSA"
]
},
{
"updated_datetime"
:
"2017-03-04T16:39:19.244769-06:00"
,
"submitter_analyte_ids"
:
[
"TCGA-VR-AA4G-10A-01W"
,
"TCGA-VR-AA4G-01A-11R"
,
"TCGA-VR-AA4G-10A-01D"
,
"TCGA-VR-AA4G-01A-11D"
,
"TCGA-VR-AA4G-01A-11W"
],
"analyte_ids"
:
[
"152d7d7a-c746-4b58-8c3f-4252454c7b7c"
,
"9090d556-bd2e-4851-8a0c-46e22cc61408"
,
"7118f4c3-b635-4428-8240-8db85281f2d9"
,
"1d8223ff-685a-4427-a3d1-f53887f2a19d"
,
"60dfb30a-bea0-426d-b11d-d5813ba39cfc"
],
"submitter_id"
:
"TCGA-VR-AA4G"
,
"case_id"
:
"df5bd25c-d70b-4126-89cb-6c838044ae3b"
,
"id"
:
"df5bd25c-d70b-4126-89cb-6c838044ae3b"
,
"disease_type"
:
"Esophageal Carcinoma"
1.10.1 Data Search and Retrieval
- 157/232 -
© 2015-2024
ANNOTATIONS ENDPOINT EXAMPLE
This example is a query for annotations contained in the GDC. It returns only the first two annotations.
Filters Examples
This section contains additional examples for using the
filters parameter.
Query Response
curl
'https://api.gdc.cancer.gov/annotations?from=0&size=2&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"category"
:
"History of unacceptable prior treatment related to a prior/other malignancy"
,
"status"
:
"Approved"
,
"entity_id"
:
"51c37449-6a2e-4c3d-a7cc-06f901e1224f"
,
"classification"
:
"Notification"
,
"entity_type"
:
"case"
,
"created_datetime"
:
"2014-06-16T00:00:00"
,
"annotation_id"
:
"3d086829-de62-5d08-b848-ce0724188ff0"
,
"notes"
:
"unknown treatment history"
,
"updated_datetime"
:
"2017-03-09T12:32:36.305475-06:00"
,
"submitter_id"
:
"20743"
,
"state"
:
"submitted"
,
"case_id"
:
"51c37449-6a2e-4c3d-a7cc-06f901e1224f"
,
"case_submitter_id"
:
"TCGA-AG-A014"
,
"entity_submitter_id"
:
"TCGA-AG-A014"
,
"id"
:
"3d086829-de62-5d08-b848-ce0724188ff0"
},
{
"category"
:
"Center QC failed"
,
"status"
:
"Approved"
,
"entity_id"
:
"733f0607-6c6b-4385-9868-fa6f155a9a2e"
,
"classification"
:
"CenterNotification"
,
"entity_type"
:
"aliquot"
,
"created_datetime"
:
"2012-07-20T00:00:00"
,
"annotation_id"
:
"5cf05f41-ce70-58a3-8ecb-6bfaf6264437"
,
"notes"
:
"RNA-seq:INSUFFICIENT INPUT MATERIAL,LOW SEQUENCE YIELD/DIVERSITY;LOW 5/3 COVERAGE RATIO"
,
"updated_datetime"
:
"2017-03-09T13:51:45.396638-06:00"
,
"submitter_id"
:
"8764"
,
"state"
:
"submitted"
,
"case_id"
:
"3e8a51bf-7e1f-4eab-af83-3c60d04db1bf"
,
"case_submitter_id"
:
"TCGA-13-0913"
,
"entity_submitter_id"
:
"TCGA-13-0913-02A-01R-1564-13"
,
"id"
:
"5cf05f41-ce70-58a3-8ecb-6bfaf6264437"
}
],
"pagination"
:
{
"count"
:
2
,
"sort"
:
""
,
"from"
:
0
,
"page"
:
1
,
"total"
:
2361
,
"pages"
:
1181
,
"size"
:
2
}
},
"warnings"
:
{}
}
1.10.1 Data Search and Retrieval
- 158/232 -
© 2015-2024
EXAMPLE: BASIC SYNTAX
The following is an example of filters syntax, including the JSON object passed to the filters parameter, the corresponding API
query, and the JSON object returned by the API. The example finds projects where the primary site is Blood.
EXAMPLE: FILTER CASES KEEPING ONLY 'MALE'
This is an example of a value-based filter:
Filter Query Response
{
"op"
:
"and"
,
"content"
:
[
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"primary_site"
,
"value"
:
[
"Blood"
]
}
}
]
}
curl
'https://api.gdc.cancer.gov/projects?filters=%7b%0d%0a++%22op%22%3a+%22and%22%2c%0d%0a++%22content%22%3a+%5b%0d%0a++++%7b%0d%0a++++++%22op%22%3a+
%22in%22%2c%0d%0a++++++%22content%22%3a+%7b%0d%0a++++++++%22field%22%3a+%22primary_site%22%2c%0d%0a++++++++%22value%22%3a+%5b%0d%0a++++++++++%22Blood%22%0d%0a+++++++
+%5d%0d%0a++++++%7d%0d%0a++++%7d%0d%0a++%5d%0d%0a%7d&pretty=true'
{
"data"
:
{
"hits"
:
[
{
"dbgap_accession_number"
:
"phs000465"
,
"disease_type"
:
[
"Acute Myeloid Leukemia"
],
"released"
:
true
,
"state"
:
"legacy"
,
"primary_site"
:
[
"Blood"
],
"project_id"
:
"TARGET-AML"
,
"id"
:
"TARGET-AML"
,
"name"
:
"Acute Myeloid Leukemia"
}
],
"pagination"
:
{
"count"
:
1
,
"sort"
:
""
,
"from"
:
0
,
"page"
:
1
,
"total"
:
1
,
"pages"
:
1
,
"size"
:
10
}
},
"warnings"
:
{}
}
Filter Query
{
"op"
:
"="
,
"content"
:
{
"field"
:
"cases.demographic.gender"
,
"value"
:
[
"male"
]
}
}
curl
'https://api.gdc.cancer.gov/cases?filters=%7b%0d%0a+++%22op%22+%3a+%22%3d%22+%2c%0d%0a+++%22content%22+%3a+%7b%0d%0a+++++++%22field%22+%3a+
%22cases.demographic.gender%22+%2c%0d%0a+++++++%22value%22+%3a+%5b+%22male%22+%5d%0d%0a+++%7d%0d%0a%7d%0d%0a&fields=demographic.gender,case_id&pretty=true'
1.10.1 Data Search and Retrieval
- 159/232 -
© 2015-2024
EXAMPLE: FILTER USING A RANGE
This is an example of filtering for age at diagnosis. The request is for cases where the age at diagnosis is between 40 and 70 years.
>Note: age_at_diagnosis is expressed in days.
EXAMPLE: MULTIPLE FIELDS
Filter projects for primary_site being Kidney or Brain and program.name being TCGA
Filter Query
{
"op"
:
"and"
,
"content"
:
[
{
"op"
:
">="
,
"content"
:
{
"field"
:
"cases.diagnoses.age_at_diagnosis"
,
"value"
:
[
14600
]
}
},
{
"op"
:
"<="
,
"content"
:
{
"field"
:
"cases.diagnoses.age_at_diagnosis"
,
"value"
:
[
25550
]
}
}
]
}
curl
'https://api.gdc.cancer.gov/cases?
filters=%7B%22op%22:%22and%22,%22content%22:%5B%7B%22op%22:%22%3E%3D%22,%22content%22:%7B%22field%22:%22cases.diagnoses.age_at_diagnosis%22,%22value%22:%5B14600%5D%7D%7D,
%7B%22op%22:%22%3C%3D%22,%22content%22:%7B%22field%22:%22cases.diagnoses.age_at_diagnosis%22,%22value%22:%5B25550%5D%7D%7D%5D%7D&fields=diagnoses.age_at_diagnosis,case_id&pretty=true'
Filter Query
{
"op"
:
"and"
,
"content"
:
[{
"op"
:
"in"
,
"content"
:
{
"field"
:
"primary_site"
,
"value"
:
[
"Kidney"
,
"Brain"
]
}
},
{
"op"
:
"in"
,
"content"
:
{
"field"
:
"program.name"
,
"value"
:
[
"TCGA"
]
}
}]
}
curl
'https://api.gdc.cancer.gov/projects?
filters=%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22primary_site%22%2C%22value%22%3A%5B%22Kidney%22%2C%22Brain%22%5D%7D%7D%2C
1.10.1 Data Search and Retrieval
- 160/232 -
© 2015-2024
1.11 Appendix A: Available Fields
The GDC API's search and retrieval endpoints provide access to fields that correspond to properties defined in the GDC Data
Dictionary. This appendix contains a list of fields available at each endpoint, and a list of field groups accessible via the expand
parameter.
1.11.1 Field Listing by Endpoint
Project Fields
Field Name
dbgap_accession_number
disease_type
name
primary_site
project_id
released
state
program.dbgap_accession_number
program.name
program.program_id
summary.case_count
summary.file_count
summary.file_size
summary.data_categories.case_count
summary.data_categories.data_category
summary.data_categories.file_count
summary.experimental_strategies.case_count
summary.experimental_strategies.experimental_strategy
summary.experimental_strategies.file_count
1.11 Appendix A: Available Fields
- 161/232 -
© 2015-2024
Case Fields
1.11.1 Field Listing by Endpoint
- 162/232 -
© 2015-2024
Field Name
aliquot_ids
analyte_ids
case_id
created_datetime
days_to_index
portion_ids
sample_ids
slide_ids
state
submitter_aliquot_ids
submitter_analyte_ids
submitter_id
submitter_portion_ids
submitter_sample_ids
submitter_slide_ids
updated_datetime
annotations.annotation_id
annotations.case_id
annotations.case_submitter_id
annotations.category
annotations.classification
annotations.created_datetime
annotations.creator
annotations.entity_id
annotations.entity_submitter_id
annotations.entity_type
annotations.legacy_created_datetime
annotations.legacy_updated_datetime
annotations.notes
annotations.state
annotations.status
annotations.submitter_id
annotations.updated_datetime
demographic.created_datetime
demographic.demographic_id
1.11.1 Field Listing by Endpoint
- 163/232 -
© 2015-2024
Field Name
demographic.ethnicity
demographic.gender
demographic.race
demographic.state
demographic.submitter_id
demographic.updated_datetime
demographic.year_of_birth
demographic.year_of_death
diagnoses.age_at_diagnosis
diagnoses.classification_of_tumor
diagnoses.created_datetime
diagnoses.days_to_birth
diagnoses.days_to_death
diagnoses.days_to_last_follow_up
diagnoses.days_to_last_known_disease_status
diagnoses.days_to_recurrence
diagnoses.diagnosis_id
diagnoses.last_known_disease_status
diagnoses.morphology
diagnoses.primary_diagnosis
diagnoses.prior_malignancy
diagnoses.progression_or_recurrence
diagnoses.site_of_resection_or_biopsy
diagnoses.state
diagnoses.submitter_id
diagnoses.tissue_or_organ_of_origin
diagnoses.tumor_grade
diagnoses.tumor_stage
diagnoses.updated_datetime
diagnoses.vital_status
diagnoses.treatments.created_datetime
diagnoses.treatments.days_to_treatment
diagnoses.treatments.state
diagnoses.treatments.submitter_id
diagnoses.treatments.therapeutic_agents
1.11.1 Field Listing by Endpoint
- 164/232 -
© 2015-2024
Field Name
diagnoses.treatments.treatment_id
diagnoses.treatments.treatment_intent_type
diagnoses.treatments.treatment_or_therapy
diagnoses.treatments.updated_datetime
exposures.alcohol_history
exposures.alcohol_intensity
exposures.bmi
exposures.cigarettes_per_day
exposures.created_datetime
exposures.exposure_id
exposures.height
exposures.state
exposures.submitter_id
exposures.updated_datetime
exposures.weight
exposures.years_smoked
family_histories.created_datetime
family_histories.family_history_id
family_histories.relationship_age_at_diagnosis
family_histories.relationship_gender
family_histories.relationship_primary_diagnosis
family_histories.relationship_type
family_histories.relative_with_cancer_history
family_histories.state
family_histories.submitter_id
family_histories.updated_datetime
files.access
files.acl
files.created_datetime
files.data_category
files.data_format
files.data_type
files.error_type
files.experimental_strategy
files.file_id
1.11.1 Field Listing by Endpoint
- 165/232 -
© 2015-2024
Field Name
files.file_name
files.file_size
files.file_state
files.md5sum
files.origin
files.platform
files.revision
files.state
files.state_comment
files.submitter_id
files.tags
files.type
files.updated_datetime
files.analysis.analysis_id
files.analysis.analysis_type
files.analysis.created_datetime
files.analysis.state
files.analysis.submitter_id
files.analysis.updated_datetime
files.analysis.workflow_end_datetime
files.analysis.workflow_link
files.analysis.workflow_start_datetime
files.analysis.workflow_type
files.analysis.workflow_version
files.analysis.input_files.access
files.analysis.input_files.created_datetime
files.analysis.input_files.data_category
files.analysis.input_files.data_format
files.analysis.input_files.data_type
files.analysis.input_files.error_type
files.analysis.input_files.experimental_strategy
files.analysis.input_files.file_id
files.analysis.input_files.file_name
files.analysis.input_files.file_size
files.analysis.input_files.file_state
1.11.1 Field Listing by Endpoint
- 166/232 -
© 2015-2024
Field Name
files.analysis.input_files.md5sum
files.analysis.input_files.platform
files.analysis.input_files.revision
files.analysis.input_files.state
files.analysis.input_files.state_comment
files.analysis.input_files.submitter_id
files.analysis.input_files.updated_datetime
files.analysis.metadata.read_groups.adapter_name
files.analysis.metadata.read_groups.adapter_sequence
files.analysis.metadata.read_groups.base_caller_name
files.analysis.metadata.read_groups.base_caller_version
files.analysis.metadata.read_groups.created_datetime
files.analysis.metadata.read_groups.experiment_name
files.analysis.metadata.read_groups.flow_cell_barcode
files.analysis.metadata.read_groups.includes_spike_ins
files.analysis.metadata.read_groups.instrument_model
files.analysis.metadata.read_groups.is_paired_end
files.analysis.metadata.read_groups.library_name
files.analysis.metadata.read_groups.library_preparation_kit_catalog_number
files.analysis.metadata.read_groups.library_preparation_kit_name
files.analysis.metadata.read_groups.library_preparation_kit_vendor
files.analysis.metadata.read_groups.library_preparation_kit_version
files.analysis.metadata.read_groups.library_selection
files.analysis.metadata.read_groups.library_strand
files.analysis.metadata.read_groups.library_strategy
files.analysis.metadata.read_groups.platform
files.analysis.metadata.read_groups.read_group_id
files.analysis.metadata.read_groups.read_group_name
files.analysis.metadata.read_groups.read_length
files.analysis.metadata.read_groups.RIN
files.analysis.metadata.read_groups.sequencing_center
files.analysis.metadata.read_groups.sequencing_date
files.analysis.metadata.read_groups.size_selection_range
files.analysis.metadata.read_groups.spike_ins_concentration
files.analysis.metadata.read_groups.spike_ins_fasta
1.11.1 Field Listing by Endpoint
- 167/232 -
© 2015-2024
Field Name
files.analysis.metadata.read_groups.state
files.analysis.metadata.read_groups.submitter_id
files.analysis.metadata.read_groups.target_capture_kit_catalog_number
files.analysis.metadata.read_groups.target_capture_kit_name
files.analysis.metadata.read_groups.target_capture_kit_target_region
files.analysis.metadata.read_groups.target_capture_kit_vendor
files.analysis.metadata.read_groups.target_capture_kit_version
files.analysis.metadata.read_groups.to_trim_adapter_sequence
files.analysis.metadata.read_groups.updated_datetime
files.analysis.metadata.read_groups.read_group_qcs.adapter_content
files.analysis.metadata.read_groups.read_group_qcs.basic_statistics
files.analysis.metadata.read_groups.read_group_qcs.created_datetime
files.analysis.metadata.read_groups.read_group_qcs.encoding
files.analysis.metadata.read_groups.read_group_qcs.fastq_name
files.analysis.metadata.read_groups.read_group_qcs.kmer_content
files.analysis.metadata.read_groups.read_group_qcs.overrepresented_sequences
files.analysis.metadata.read_groups.read_group_qcs.per_base_n_content
files.analysis.metadata.read_groups.read_group_qcs.per_base_sequence_content
files.analysis.metadata.read_groups.read_group_qcs.per_base_sequence_quality
files.analysis.metadata.read_groups.read_group_qcs.per_sequence_gc_content
files.analysis.metadata.read_groups.read_group_qcs.per_sequence_quality_score
files.analysis.metadata.read_groups.read_group_qcs.per_tile_sequence_quality
files.analysis.metadata.read_groups.read_group_qcs.percent_gc_content
files.analysis.metadata.read_groups.read_group_qcs.read_group_qc_id
files.analysis.metadata.read_groups.read_group_qcs.sequence_duplication_levels
files.analysis.metadata.read_groups.read_group_qcs.sequence_length_distribution
files.analysis.metadata.read_groups.read_group_qcs.state
files.analysis.metadata.read_groups.read_group_qcs.submitter_id
files.analysis.metadata.read_groups.read_group_qcs.total_sequences
files.analysis.metadata.read_groups.read_group_qcs.updated_datetime
files.analysis.metadata.read_groups.read_group_qcs.workflow_end_datetime
files.analysis.metadata.read_groups.read_group_qcs.workflow_link
files.analysis.metadata.read_groups.read_group_qcs.workflow_start_datetime
files.analysis.metadata.read_groups.read_group_qcs.workflow_type
files.analysis.metadata.read_groups.read_group_qcs.workflow_version
1.11.1 Field Listing by Endpoint
- 168/232 -
© 2015-2024
Field Name
files.archive.archive_id
files.archive.created_datetime
files.archive.data_category
files.archive.data_format
files.archive.data_type
files.archive.error_type
files.archive.file_name
files.archive.file_size
files.archive.file_state
files.archive.md5sum
files.archive.revision
files.archive.state
files.archive.state_comment
files.archive.submitter_id
files.archive.updated_datetime
files.cases.aliquot_ids
files.cases.analyte_ids
files.cases.case_id
files.cases.created_datetime
files.cases.days_to_index
files.cases.portion_ids
files.cases.sample_ids
files.cases.slide_ids
files.cases.state
files.cases.submitter_aliquot_ids
files.cases.submitter_analyte_ids
files.cases.submitter_id
files.cases.submitter_portion_ids
files.cases.submitter_sample_ids
files.cases.submitter_slide_ids
files.cases.updated_datetime
files.cases.annotations.annotation_id
files.cases.annotations.case_id
files.cases.annotations.case_submitter_id
files.cases.annotations.category
1.11.1 Field Listing by Endpoint
- 169/232 -
© 2015-2024
Field Name
files.cases.annotations.classification
files.cases.annotations.created_datetime
files.cases.annotations.creator
files.cases.annotations.entity_id
files.cases.annotations.entity_submitter_id
files.cases.annotations.entity_type
files.cases.annotations.legacy_created_datetime
files.cases.annotations.legacy_updated_datetime
files.cases.annotations.notes
files.cases.annotations.state
files.cases.annotations.status
files.cases.annotations.submitter_id
files.cases.annotations.updated_datetime
files.cases.demographic.created_datetime
files.cases.demographic.demographic_id
files.cases.demographic.ethnicity
files.cases.demographic.gender
files.cases.demographic.race
files.cases.demographic.state
files.cases.demographic.submitter_id
files.cases.demographic.updated_datetime
files.cases.demographic.year_of_birth
files.cases.demographic.year_of_death
files.cases.diagnoses.age_at_diagnosis
files.cases.diagnoses.classification_of_tumor
files.cases.diagnoses.created_datetime
files.cases.diagnoses.days_to_birth
files.cases.diagnoses.days_to_death
files.cases.diagnoses.days_to_last_follow_up
files.cases.diagnoses.days_to_last_known_disease_status
files.cases.diagnoses.days_to_recurrence
files.cases.diagnoses.diagnosis_id
files.cases.diagnoses.last_known_disease_status
files.cases.diagnoses.morphology
files.cases.diagnoses.primary_diagnosis
1.11.1 Field Listing by Endpoint
- 170/232 -
© 2015-2024
Field Name
files.cases.diagnoses.prior_malignancy
files.cases.diagnoses.progression_or_recurrence
files.cases.diagnoses.site_of_resection_or_biopsy
files.cases.diagnoses.state
files.cases.diagnoses.submitter_id
files.cases.diagnoses.tissue_or_organ_of_origin
files.cases.diagnoses.tumor_grade
files.cases.diagnoses.tumor_stage
files.cases.diagnoses.updated_datetime
files.cases.diagnoses.vital_status
files.cases.diagnoses.treatments.created_datetime
files.cases.diagnoses.treatments.days_to_treatment
files.cases.diagnoses.treatments.state
files.cases.diagnoses.treatments.submitter_id
files.cases.diagnoses.treatments.therapeutic_agents
files.cases.diagnoses.treatments.treatment_id
files.cases.diagnoses.treatments.treatment_intent_type
files.cases.diagnoses.treatments.treatment_or_therapy
files.cases.diagnoses.treatments.updated_datetime
files.cases.exposures.alcohol_history
files.cases.exposures.alcohol_intensity
files.cases.exposures.bmi
files.cases.exposures.cigarettes_per_day
files.cases.exposures.created_datetime
files.cases.exposures.exposure_id
files.cases.exposures.height
files.cases.exposures.state
files.cases.exposures.submitter_id
files.cases.exposures.updated_datetime
files.cases.exposures.weight
files.cases.exposures.years_smoked
files.cases.family_histories.created_datetime
files.cases.family_histories.family_history_id
files.cases.family_histories.relationship_age_at_diagnosis
files.cases.family_histories.relationship_gender
1.11.1 Field Listing by Endpoint
- 171/232 -
© 2015-2024
Field Name
files.cases.family_histories.relationship_primary_diagnosis
files.cases.family_histories.relationship_type
files.cases.family_histories.relative_with_cancer_history
files.cases.family_histories.state
files.cases.family_histories.submitter_id
files.cases.family_histories.updated_datetime
files.cases.files.created_datetime
files.cases.files.error_type
files.cases.files.file_id
files.cases.files.file_name
files.cases.files.file_size
files.cases.files.file_state
files.cases.files.md5sum
files.cases.files.state
files.cases.files.state_comment
files.cases.files.submitter_id
files.cases.files.updated_datetime
files.cases.project.dbgap_accession_number
files.cases.project.disease_type
files.cases.project.name
files.cases.project.primary_site
files.cases.project.project_id
files.cases.project.released
files.cases.project.state
files.cases.project.program.dbgap_accession_number
files.cases.project.program.name
files.cases.project.program.program_id
files.cases.samples.composition
files.cases.samples.created_datetime
files.cases.samples.current_weight
files.cases.samples.days_to_collection
files.cases.samples.days_to_sample_procurement
files.cases.samples.freezing_method
files.cases.samples.initial_weight
files.cases.samples.intermediate_dimension
1.11.1 Field Listing by Endpoint
- 172/232 -
© 2015-2024
Field Name
files.cases.samples.is_ffpe
files.cases.samples.longest_dimension
files.cases.samples.oct_embedded
files.cases.samples.pathology_report_uuid
files.cases.samples.preservation_method
files.cases.samples.sample_id
files.cases.samples.sample_type
files.cases.samples.sample_type_id
files.cases.samples.shortest_dimension
files.cases.samples.state
files.cases.samples.submitter_id
files.cases.samples.time_between_clamping_and_freezing
files.cases.samples.time_between_excision_and_freezing
files.cases.samples.tissue_type
files.cases.samples.tumor_code
files.cases.samples.tumor_code_id
files.cases.samples.tumor_descriptor
files.cases.samples.updated_datetime
files.cases.samples.annotations.annotation_id
files.cases.samples.annotations.case_id
files.cases.samples.annotations.case_submitter_id
files.cases.samples.annotations.category
files.cases.samples.annotations.classification
files.cases.samples.annotations.created_datetime
files.cases.samples.annotations.creator
files.cases.samples.annotations.entity_id
files.cases.samples.annotations.entity_submitter_id
files.cases.samples.annotations.entity_type
files.cases.samples.annotations.legacy_created_datetime
files.cases.samples.annotations.legacy_updated_datetime
files.cases.samples.annotations.notes
files.cases.samples.annotations.state
files.cases.samples.annotations.status
files.cases.samples.annotations.submitter_id
files.cases.samples.annotations.updated_datetime
1.11.1 Field Listing by Endpoint
- 173/232 -
© 2015-2024
Field Name
files.cases.samples.portions.created_datetime
files.cases.samples.portions.creation_datetime
files.cases.samples.portions.is_ffpe
files.cases.samples.portions.portion_id
files.cases.samples.portions.portion_number
files.cases.samples.portions.state
files.cases.samples.portions.submitter_id
files.cases.samples.portions.updated_datetime
files.cases.samples.portions.weight
files.cases.samples.portions.analytes.a260_a280_ratio
files.cases.samples.portions.analytes.amount
files.cases.samples.portions.analytes.analyte_id
files.cases.samples.portions.analytes.analyte_type
files.cases.samples.portions.analytes.analyte_type_id
files.cases.samples.portions.analytes.concentration
files.cases.samples.portions.analytes.created_datetime
files.cases.samples.portions.analytes.spectrophotometer_method
files.cases.samples.portions.analytes.state
files.cases.samples.portions.analytes.submitter_id
files.cases.samples.portions.analytes.updated_datetime
files.cases.samples.portions.analytes.well_number
files.cases.samples.portions.analytes.aliquots.aliquot_id
files.cases.samples.portions.analytes.aliquots.amount
files.cases.samples.portions.analytes.aliquots.analyte_type
files.cases.samples.portions.analytes.aliquots.analyte_type_id
files.cases.samples.portions.analytes.aliquots.concentration
files.cases.samples.portions.analytes.aliquots.created_datetime
files.cases.samples.portions.analytes.aliquots.source_center
files.cases.samples.portions.analytes.aliquots.state
files.cases.samples.portions.analytes.aliquots.submitter_id
files.cases.samples.portions.analytes.aliquots.updated_datetime
files.cases.samples.portions.analytes.aliquots.annotations.annotation_id
files.cases.samples.portions.analytes.aliquots.annotations.case_id
files.cases.samples.portions.analytes.aliquots.annotations.case_submitter_id
files.cases.samples.portions.analytes.aliquots.annotations.category
1.11.1 Field Listing by Endpoint
- 174/232 -
© 2015-2024
Field Name
files.cases.samples.portions.analytes.aliquots.annotations.classification
files.cases.samples.portions.analytes.aliquots.annotations.created_datetime
files.cases.samples.portions.analytes.aliquots.annotations.creator
files.cases.samples.portions.analytes.aliquots.annotations.entity_id
files.cases.samples.portions.analytes.aliquots.annotations.entity_submitter_id
files.cases.samples.portions.analytes.aliquots.annotations.entity_type
files.cases.samples.portions.analytes.aliquots.annotations.legacy_created_datetime
files.cases.samples.portions.analytes.aliquots.annotations.legacy_updated_datetime
files.cases.samples.portions.analytes.aliquots.annotations.notes
files.cases.samples.portions.analytes.aliquots.annotations.state
files.cases.samples.portions.analytes.aliquots.annotations.status
files.cases.samples.portions.analytes.aliquots.annotations.submitter_id
files.cases.samples.portions.analytes.aliquots.annotations.updated_datetime
files.cases.samples.portions.analytes.aliquots.center.center_id
files.cases.samples.portions.analytes.aliquots.center.center_type
files.cases.samples.portions.analytes.aliquots.center.code
files.cases.samples.portions.analytes.aliquots.center.name
files.cases.samples.portions.analytes.aliquots.center.namespace
files.cases.samples.portions.analytes.aliquots.center.short_name
files.cases.samples.portions.analytes.annotations.annotation_id
files.cases.samples.portions.analytes.annotations.case_id
files.cases.samples.portions.analytes.annotations.case_submitter_id
files.cases.samples.portions.analytes.annotations.category
files.cases.samples.portions.analytes.annotations.classification
files.cases.samples.portions.analytes.annotations.created_datetime
files.cases.samples.portions.analytes.annotations.creator
files.cases.samples.portions.analytes.annotations.entity_id
files.cases.samples.portions.analytes.annotations.entity_submitter_id
files.cases.samples.portions.analytes.annotations.entity_type
files.cases.samples.portions.analytes.annotations.legacy_created_datetime
files.cases.samples.portions.analytes.annotations.legacy_updated_datetime
files.cases.samples.portions.analytes.annotations.notes
files.cases.samples.portions.analytes.annotations.state
files.cases.samples.portions.analytes.annotations.status
files.cases.samples.portions.analytes.annotations.submitter_id
1.11.1 Field Listing by Endpoint
- 175/232 -
© 2015-2024
Field Name
files.cases.samples.portions.analytes.annotations.updated_datetime
files.cases.samples.portions.annotations.annotation_id
files.cases.samples.portions.annotations.case_id
files.cases.samples.portions.annotations.case_submitter_id
files.cases.samples.portions.annotations.category
files.cases.samples.portions.annotations.classification
files.cases.samples.portions.annotations.created_datetime
files.cases.samples.portions.annotations.creator
files.cases.samples.portions.annotations.entity_id
files.cases.samples.portions.annotations.entity_submitter_id
files.cases.samples.portions.annotations.entity_type
files.cases.samples.portions.annotations.legacy_created_datetime
files.cases.samples.portions.annotations.legacy_updated_datetime
files.cases.samples.portions.annotations.notes
files.cases.samples.portions.annotations.state
files.cases.samples.portions.annotations.status
files.cases.samples.portions.annotations.submitter_id
files.cases.samples.portions.annotations.updated_datetime
files.cases.samples.portions.center.center_id
files.cases.samples.portions.center.center_type
files.cases.samples.portions.center.code
files.cases.samples.portions.center.name
files.cases.samples.portions.center.namespace
files.cases.samples.portions.center.short_name
files.cases.samples.portions.slides.created_datetime
files.cases.samples.portions.slides.number_proliferating_cells
files.cases.samples.portions.slides.percent_eosinophil_infiltration
files.cases.samples.portions.slides.percent_granulocyte_infiltration
files.cases.samples.portions.slides.percent_inflam_infiltration
files.cases.samples.portions.slides.percent_lymphocyte_infiltration
files.cases.samples.portions.slides.percent_monocyte_infiltration
files.cases.samples.portions.slides.percent_necrosis
files.cases.samples.portions.slides.percent_neutrophil_infiltration
files.cases.samples.portions.slides.percent_normal_cells
files.cases.samples.portions.slides.percent_stromal_cells
1.11.1 Field Listing by Endpoint
- 176/232 -
© 2015-2024
Field Name
files.cases.samples.portions.slides.percent_tumor_cells
files.cases.samples.portions.slides.percent_tumor_nuclei
files.cases.samples.portions.slides.section_location
files.cases.samples.portions.slides.slide_id
files.cases.samples.portions.slides.state
files.cases.samples.portions.slides.submitter_id
files.cases.samples.portions.slides.updated_datetime
files.cases.samples.portions.slides.annotations.annotation_id
files.cases.samples.portions.slides.annotations.case_id
files.cases.samples.portions.slides.annotations.case_submitter_id
files.cases.samples.portions.slides.annotations.category
files.cases.samples.portions.slides.annotations.classification
files.cases.samples.portions.slides.annotations.created_datetime
files.cases.samples.portions.slides.annotations.creator
files.cases.samples.portions.slides.annotations.entity_id
files.cases.samples.portions.slides.annotations.entity_submitter_id
files.cases.samples.portions.slides.annotations.entity_type
files.cases.samples.portions.slides.annotations.legacy_created_datetime
files.cases.samples.portions.slides.annotations.legacy_updated_datetime
files.cases.samples.portions.slides.annotations.notes
files.cases.samples.portions.slides.annotations.state
files.cases.samples.portions.slides.annotations.status
files.cases.samples.portions.slides.annotations.submitter_id
files.cases.samples.portions.slides.annotations.updated_datetime
files.cases.summary.file_count
files.cases.summary.file_size
files.cases.summary.data_categories.data_category
files.cases.summary.data_categories.file_count
files.cases.summary.experimental_strategies.experimental_strategy
files.cases.summary.experimental_strategies.file_count
files.cases.tissue_source_site.bcr_id
files.cases.tissue_source_site.code
files.cases.tissue_source_site.name
files.cases.tissue_source_site.project
files.cases.tissue_source_site.tissue_source_site_id
1.11.1 Field Listing by Endpoint
- 177/232 -
© 2015-2024
Field Name
files.center.center_id
files.center.center_type
files.center.code
files.center.name
files.center.namespace
files.center.short_name
files.downstream_analyses.analysis_id
files.downstream_analyses.analysis_type
files.downstream_analyses.created_datetime
files.downstream_analyses.state
files.downstream_analyses.submitter_id
files.downstream_analyses.updated_datetime
files.downstream_analyses.workflow_end_datetime
files.downstream_analyses.workflow_link
files.downstream_analyses.workflow_start_datetime
files.downstream_analyses.workflow_type
files.downstream_analyses.workflow_version
files.downstream_analyses.output_files.access
files.downstream_analyses.output_files.created_datetime
files.downstream_analyses.output_files.data_category
files.downstream_analyses.output_files.data_format
files.downstream_analyses.output_files.data_type
files.downstream_analyses.output_files.error_type
files.downstream_analyses.output_files.experimental_strategy
files.downstream_analyses.output_files.file_id
files.downstream_analyses.output_files.file_name
files.downstream_analyses.output_files.file_size
files.downstream_analyses.output_files.file_state
files.downstream_analyses.output_files.md5sum
files.downstream_analyses.output_files.platform
files.downstream_analyses.output_files.revision
files.downstream_analyses.output_files.state
files.downstream_analyses.output_files.state_comment
files.downstream_analyses.output_files.submitter_id
files.downstream_analyses.output_files.updated_datetime
1.11.1 Field Listing by Endpoint
- 178/232 -
© 2015-2024
Field Name
files.index_files.access
files.index_files.created_datetime
files.index_files.data_category
files.index_files.data_format
files.index_files.data_type
files.index_files.error_type
files.index_files.experimental_strategy
files.index_files.file_id
files.index_files.file_name
files.index_files.file_size
files.index_files.file_state
files.index_files.md5sum
files.index_files.platform
files.index_files.revision
files.index_files.state
files.index_files.state_comment
files.index_files.submitter_id
files.index_files.updated_datetime
files.metadata_files.access
files.metadata_files.created_datetime
files.metadata_files.data_category
files.metadata_files.data_format
files.metadata_files.data_type
files.metadata_files.error_type
files.metadata_files.file_id
files.metadata_files.file_name
files.metadata_files.file_size
files.metadata_files.file_state
files.metadata_files.md5sum
files.metadata_files.state
files.metadata_files.state_comment
files.metadata_files.submitter_id
files.metadata_files.type
files.metadata_files.updated_datetime
project.dbgap_accession_number
1.11.1 Field Listing by Endpoint
- 179/232 -
© 2015-2024
Field Name
project.disease_type
project.name
project.primary_site
project.project_id
project.released
project.state
project.program.dbgap_accession_number
project.program.name
project.program.program_id
samples.composition
samples.created_datetime
samples.current_weight
samples.days_to_collection
samples.days_to_sample_procurement
samples.freezing_method
samples.initial_weight
samples.intermediate_dimension
samples.is_ffpe
samples.longest_dimension
samples.oct_embedded
samples.pathology_report_uuid
samples.preservation_method
samples.sample_id
samples.sample_type
samples.sample_type_id
samples.shortest_dimension
samples.state
samples.submitter_id
samples.time_between_clamping_and_freezing
samples.time_between_excision_and_freezing
samples.tissue_type
samples.tumor_code
samples.tumor_code_id
samples.tumor_descriptor
samples.updated_datetime
1.11.1 Field Listing by Endpoint
- 180/232 -
© 2015-2024
Field Name
samples.annotations.annotation_id
samples.annotations.case_id
samples.annotations.case_submitter_id
samples.annotations.category
samples.annotations.classification
samples.annotations.created_datetime
samples.annotations.creator
samples.annotations.entity_id
samples.annotations.entity_submitter_id
samples.annotations.entity_type
samples.annotations.legacy_creat
samples.annotations.legacy_updated_datetime
samples.annotations.notes
samples.annotations.state
samples.annotations.status
samples.annotations.submitter_id
samples.annotations.updated_datetime
samples.portions.created_datetime
samples.portions.creation_datetime
samples.portions.is_ffpe
samples.portions.portion_id
samples.portions.portion_number
samples.portions.state
samples.portions.submitter_id
samples.portions.updated_datetime
samples.portions.weight
samples.portions.analytes.a260_a280_ratio
samples.portions.analytes.amount
samples.portions.analytes.analyte_id
samples.portions.analytes.analyte_type
samples.portions.analytes.analyte_type_id
samples.portions.analytes.concentration
samples.portions.analytes.created_datetime
samples.portions.analytes.spectrophotometer_method
samples.portions.analytes.state
1.11.1 Field Listing by Endpoint
- 181/232 -
© 2015-2024
Field Name
samples.portions.analytes.submitter_id
samples.portions.analytes.updated_datetime
samples.portions.analytes.well_number
samples.portions.analytes.aliquots.aliquot_id
samples.portions.analytes.aliquots.amount
samples.portions.analytes.aliquots.analyte_type
samples.portions.analytes.aliquots.analyte_type_id
samples.portions.analytes.aliquots.concentration
samples.portions.analytes.aliquots.created_datetime
samples.portions.analytes.aliquots.source_center
samples.portions.analytes.aliquots.state
samples.portions.analytes.aliquots.submitter_id
samples.portions.analytes.aliquots.updated_datetime
samples.portions.analytes.aliquots.annotations.annotation_id
samples.portions.analytes.aliquots.annotations.case_id
samples.portions.analytes.aliquots.annotations.case_submitter_id
samples.portions.analytes.aliquots.annotations.category
samples.portions.analytes.aliquots.annotations.classification
samples.portions.analytes.aliquots.annotations.created_datetime
samples.portions.analytes.aliquots.annotations.creator
samples.portions.analytes.aliquots.annotations.entity_id
samples.portions.analytes.aliquots.annotations.entity_submitter_id
samples.portions.analytes.aliquots.annotations.entity_type
samples.portions.analytes.aliquots.annotations.legacy_created_datetime
samples.portions.analytes.aliquots.annotations.legacy_updated_datetime
samples.portions.analytes.aliquots.annotations.notes
samples.portions.analytes.aliquots.annotations.state
samples.portions.analytes.aliquots.annotations.status
samples.portions.analytes.aliquots.annotations.submitter_id
samples.portions.analytes.aliquots.annotations.updated_datetime
samples.portions.analytes.aliquots.center.center_id
samples.portions.analytes.aliquots.center.center_type
samples.portions.analytes.aliquots.center.code
samples.portions.analytes.aliquots.center.name
samples.portions.analytes.aliquots.center.namespace
1.11.1 Field Listing by Endpoint
- 182/232 -
© 2015-2024
Field Name
samples.portions.analytes.aliquots.center.short_name
samples.portions.analytes.annotations.annotation_id
samples.portions.analytes.annotations.case_id
samples.portions.analytes.annotations.case_submitter_id
samples.portions.analytes.annotations.category
samples.portions.analytes.annotations.classification
samples.portions.analytes.annotations.created_datetime
samples.portions.analytes.annotations.creator
samples.portions.analytes.annotations.entity_id
samples.portions.analytes.annotations.entity_submitter_id
samples.portions.analytes.annotations.entity_type
samples.portions.analytes.annotations.legacy_created_datetime
samples.portions.analytes.annotations.legacy_updated_datetime
samples.portions.analytes.annotations.notes
samples.portions.analytes.annotations.state
samples.portions.analytes.annotations.status
samples.portions.analytes.annotations.submitter_id
samples.portions.analytes.annotations.updated_datetime
samples.portions.annotations.annotation_id
samples.portions.annotations.case_id
samples.portions.annotations.case_submitter_id
samples.portions.annotations.category
samples.portions.annotations.classification
samples.portions.annotations.created_datetime
samples.portions.annotations.creator
samples.portions.annotations.entity_id
samples.portions.annotations.entity_submitter_id
samples.portions.annotations.entity_type
samples.portions.annotations.legacy_created_datetime
samples.portions.annotations.legacy_updated_datetime
samples.portions.annotations.notes
samples.portions.annotations.state
samples.portions.annotations.status
samples.portions.annotations.submitter_id
samples.portions.annotations.updated_datetime
1.11.1 Field Listing by Endpoint
- 183/232 -
© 2015-2024
Field Name
samples.portions.center.center_id
samples.portions.center.center_type
samples.portions.center.code
samples.portions.center.name
samples.portions.center.namespace
samples.portions.center.short_name
samples.portions.slides.created_datetime
samples.portions.slides.number_proliferating_cells
samples.portions.slides.percent_eosinophil_infiltration
samples.portions.slides.percent_granulocyte_infiltration
samples.portions.slides.percent_inflam_infiltration
samples.portions.slides.percent_lymphocyte_infiltration
samples.portions.slides.percent_monocyte_infiltration
samples.portions.slides.percent_necrosis
samples.portions.slides.percent_neutrophil_infiltration
samples.portions.slides.percent_normal_cells
samples.portions.slides.percent_stromal_cells
samples.portions.slides.percent_tumor_cells
samples.portions.slides.percent_tumor_nuclei
samples.portions.slides.section_location
samples.portions.slides.slide_id
samples.portions.slides.state
samples.portions.slides.submitter_id
samples.portions.slides.updated_datetime
samples.portions.slides.annotations.annotation_id
samples.portions.slides.annotations.case_id
samples.portions.slides.annotations.case_submitter_id
samples.portions.slides.annotations.category
samples.portions.slides.annotations.classification
samples.portions.slides.annotations.created_datetime
samples.portions.slides.annotations.creator
samples.portions.slides.annotations.entity_id
samples.portions.slides.annotations.entity_submitter_id
samples.portions.slides.annotations.entity_type
samples.portions.slides.annotations.legacy_created_datetime
1.11.1 Field Listing by Endpoint
- 184/232 -
© 2015-2024
Field Name
samples.portions.slides.annotations.legacy_updated_datetime
samples.portions.slides.annotations.notes
samples.portions.slides.annotations.state
samples.portions.slides.annotations.status
samples.portions.slides.annotations.submitter_id
samples.portions.slides.annotations.updated_datetime
summary.file_count
summary.file_size
summary.data_categories.data_category
summary.data_categories.file_count
summary.experimental_strategies.experimental_strategy
summary.experimental_strategies.file_count
tissue_source_site.bcr_id
tissue_source_site.code
tissue_source_site.name
tissue_source_site.project
tissue_source_site.tissue_source_site_id
1.11.1 Field Listing by Endpoint
- 185/232 -
© 2015-2024
File Fields
1.11.1 Field Listing by Endpoint
- 186/232 -
© 2015-2024
Field Name
access
acl
created_datetime
data_category
data_format
data_type
error_type
experimental_strategy
file_id
file_name
file_size
file_state
md5sum
origin
platform
revision
state
state_comment
submitter_id
tags
type
updated_datetime
analysis.analysis_id
analysis.analysis_type
analysis.created_datetime
analysis.state
analysis.submitter_id
analysis.updated_datetime
analysis.workflow_end_datetime
analysis.workflow_link
analysis.workflow_start_datetime
analysis.workflow_type
analysis.workflow_version
analysis.input_files.access
analysis.input_files.created_datetime
1.11.1 Field Listing by Endpoint
- 187/232 -
© 2015-2024
Field Name
analysis.input_files.data_category
analysis.input_files.data_format
analysis.input_files.data_type
analysis.input_files.error_type
analysis.input_files.experimental_strategy
analysis.input_files.file_id
analysis.input_files.file_name
analysis.input_files.file_size
analysis.input_files.file_state
analysis.input_files.md5sum
analysis.input_files.platform
analysis.input_files.revision
analysis.input_files.state
analysis.input_files.state_comment
analysis.input_files.submitter_id
analysis.input_files.updated_datetime
analysis.metadata.read_groups.adapter_name
analysis.metadata.read_groups.adapter_sequence
analysis.metadata.read_groups.base_caller_name
analysis.metadata.read_groups.base_caller_version
analysis.metadata.read_groups.created_datetime
analysis.metadata.read_groups.experiment_name
analysis.metadata.read_groups.flow_cell_barcode
analysis.metadata.read_groups.includes_spike_ins
analysis.metadata.read_groups.instrument_model
analysis.metadata.read_groups.is_paired_end
analysis.metadata.read_groups.library_name
analysis.metadata.read_groups.library_preparation_kit_catalog_number
analysis.metadata.read_groups.library_preparation_kit_name
analysis.metadata.read_groups.library_preparation_kit_vendor
analysis.metadata.read_groups.library_preparation_kit_version
analysis.metadata.read_groups.library_selection
analysis.metadata.read_groups.library_strand
analysis.metadata.read_groups.library_strategy
analysis.metadata.read_groups.platform
1.11.1 Field Listing by Endpoint
- 188/232 -
© 2015-2024
Field Name
analysis.metadata.read_groups.read_group_id
analysis.metadata.read_groups.read_group_name
analysis.metadata.read_groups.read_length
analysis.metadata.read_groups.RIN
analysis.metadata.read_groups.sequencing_center
analysis.metadata.read_groups.sequencing_date
analysis.metadata.read_groups.size_selection_range
analysis.metadata.read_groups.spike_ins_concentration
analysis.metadata.read_groups.spike_ins_fasta
analysis.metadata.read_groups.state
analysis.metadata.read_groups.submitter_id
analysis.metadata.read_groups.target_capture_kit_catalog_number
analysis.metadata.read_groups.target_capture_kit_name
analysis.metadata.read_groups.target_capture_kit_target_region
analysis.metadata.read_groups.target_capture_kit_vendor
analysis.metadata.read_groups.target_capture_kit_version
analysis.metadata.read_groups.to_trim_adapter_sequence
analysis.metadata.read_groups.updated_datetime
analysis.metadata.read_groups.read_group_qcs.adapter_content
analysis.metadata.read_groups.read_group_qcs.basic_statistics
analysis.metadata.read_groups.read_group_qcs.created_datetime
analysis.metadata.read_groups.read_group_qcs.encoding
analysis.metadata.read_groups.read_group_qcs.fastq_name
analysis.metadata.read_groups.read_group_qcs.kmer_content
analysis.metadata.read_groups.read_group_qcs.overrepresented_sequences
analysis.metadata.read_groups.read_group_qcs.per_base_n_content
analysis.metadata.read_groups.read_group_qcs.per_base_sequence_content
analysis.metadata.read_groups.read_group_qcs.per_base_sequence_quality
analysis.metadata.read_groups.read_group_qcs.per_sequence_gc_content
analysis.metadata.read_groups.read_group_qcs.per_sequence_quality_score
analysis.metadata.read_groups.read_group_qcs.per_tile_sequence_quality
analysis.metadata.read_groups.read_group_qcs.percent_gc_content
analysis.metadata.read_groups.read_group_qcs.read_group_qc_id
analysis.metadata.read_groups.read_group_qcs.sequence_duplication_levels
analysis.metadata.read_groups.read_group_qcs.sequence_length_distribution
1.11.1 Field Listing by Endpoint
- 189/232 -
© 2015-2024
Field Name
analysis.metadata.read_groups.read_group_qcs.state
analysis.metadata.read_groups.read_group_qcs.submitter_id
analysis.metadata.read_groups.read_group_qcs.total_sequences
analysis.metadata.read_groups.read_group_qcs.updated_datetime
analysis.metadata.read_groups.read_group_qcs.workflow_end_datetime
analysis.metadata.read_groups.read_group_qcs.workflow_link
analysis.metadata.read_groups.read_group_qcs.workflow_start_datetime
analysis.metadata.read_groups.read_group_qcs.workflow_type
analysis.metadata.read_groups.read_group_qcs.workflow_version
annotations.annotation_id
annotations.case_id
annotations.case_submitter_id
annotations.category
annotations.classification
annotations.created_datetime
annotations.creator
annotations.entity_id
annotations.entity_submitter_id
annotations.entity_type
annotations.legacy_created_datetime
annotations.legacy_updated_datetime
annotations.notes
annotations.state
annotations.status
annotations.submitter_id
annotations.updated_datetime
archive.archive_id
archive.created_datetime
archive.data_category
archive.data_format
archive.data_type
archive.error_type
archive.file_name
archive.file_size
archive.file_state
1.11.1 Field Listing by Endpoint
- 190/232 -
© 2015-2024
Field Name
archive.md5sum
archive.revision
archive.state
archive.state_comment
archive.submitter_id
archive.updated_datetime
associated_entities.case_id
associated_entities.entity_id
associated_entities.entity_submitter_id
associated_entities.entity_type
cases.aliquot_ids
cases.analyte_ids
cases.case_id
cases.created_datetime
cases.days_to_index
cases.portion_ids
cases.sample_ids
cases.slide_ids
cases.state
cases.submitter_aliquot_ids
cases.submitter_analyte_ids
cases.submitter_id
cases.submitter_portion_ids
cases.submitter_sample_ids
cases.submitter_slide_ids
cases.updated_datetime
cases.annotations.annotation_id
cases.annotations.case_id
cases.annotations.case_submitter_id
cases.annotations.category
cases.annotations.classification
cases.annotations.created_datetime
cases.annotations.creator
cases.annotations.entity_id
cases.annotations.entity_submitter_id
1.11.1 Field Listing by Endpoint
- 191/232 -
© 2015-2024
Field Name
cases.annotations.entity_type
cases.annotations.legacy_created_datetime
cases.annotations.legacy_updated_datetime
cases.annotations.notes
cases.annotations.state
cases.annotations.status
cases.annotations.submitter_id
cases.annotations.updated_datetime
cases.demographic.created_datetime
cases.demographic.demographic_id
cases.demographic.ethnicity
cases.demographic.gender
cases.demographic.race
cases.demographic.state
cases.demographic.submitter_id
cases.demographic.updated_datetime
cases.demographic.year_of_birth
cases.demographic.year_of_death
cases.diagnoses.age_at_diagnosis
cases.diagnoses.classification_of_tumor
cases.diagnoses.created_datetime
cases.diagnoses.days_to_birth
cases.diagnoses.days_to_death
cases.diagnoses.days_to_last_follow_up
cases.diagnoses.days_to_last_known_disease_status
cases.diagnoses.days_to_recurrence
cases.diagnoses.diagnosis_id
cases.diagnoses.last_known_disease_status
cases.diagnoses.morphology
cases.diagnoses.primary_diagnosis
cases.diagnoses.prior_malignancy
cases.diagnoses.progression_or_recurrence
cases.diagnoses.site_of_resection_or_biopsy
cases.diagnoses.state
cases.diagnoses.submitter_id
1.11.1 Field Listing by Endpoint
- 192/232 -
© 2015-2024
Field Name
cases.diagnoses.tissue_or_organ_of_origin
cases.diagnoses.tumor_grade
cases.diagnoses.tumor_stage
cases.diagnoses.updated_datetime
cases.diagnoses.vital_status
cases.diagnoses.treatments.created_datetime
cases.diagnoses.treatments.days_to_treatment
cases.diagnoses.treatments.state
cases.diagnoses.treatments.submitter_id
cases.diagnoses.treatments.therapeutic_agents
cases.diagnoses.treatments.treatment_id
cases.diagnoses.treatments.treatment_intent_type
cases.diagnoses.treatments.treatment_or_therapy
cases.diagnoses.treatments.updated_datetime
cases.exposures.alcohol_history
cases.exposures.alcohol_intensity
cases.exposures.bmi
cases.exposures.cigarettes_per_day
cases.exposures.created_datetime
cases.exposures.exposure_id
cases.exposures.height
cases.exposures.state
cases.exposures.submitter_id
cases.exposures.updated_datetime
cases.exposures.weight
cases.exposures.years_smoked
cases.family_histories.created_datetime
cases.family_histories.family_history_id
cases.family_histories.relationship_age_at_diagnosis
cases.family_histories.relationship_gender
cases.family_histories.relationship_primary_diagnosis
cases.family_histories.relationship_type
cases.family_histories.relative_with_cancer_history
cases.family_histories.state
cases.family_histories.submitter_id
1.11.1 Field Listing by Endpoint
- 193/232 -
© 2015-2024
Field Name
cases.family_histories.updated_datetime
cases.files.created_datetime
cases.files.error_type
cases.files.file_id
cases.files.file_name
cases.files.file_size
cases.files.file_state
cases.files.md5sum
cases.files.state
cases.files.state_comment
cases.files.submitter_id
cases.files.updated_datetime
cases.project.dbgap_accession_number
cases.project.disease_type
cases.project.name
cases.project.primary_site
cases.project.project_id
cases.project.released
cases.project.state
cases.project.program.dbgap_accession_number
cases.project.program.name
cases.project.program.program_id
cases.samples.composition
cases.samples.created_datetime
cases.samples.current_weight
cases.samples.days_to_collection
cases.samples.days_to_sample_procurement
cases.samples.freezing_method
cases.samples.initial_weight
cases.samples.intermediate_dimension
cases.samples.is_ffpe
cases.samples.longest_dimension
cases.samples.oct_embedded
cases.samples.pathology_report_uuid
cases.samples.preservation_method
1.11.1 Field Listing by Endpoint
- 194/232 -
© 2015-2024
Field Name
cases.samples.sample_id
cases.samples.sample_type
cases.samples.sample_type_id
cases.samples.shortest_dimension
cases.samples.state
cases.samples.submitter_id
cases.samples.time_between_clamping_and_freezing
cases.samples.time_between_excision_and_freezing
cases.samples.tissue_type
cases.samples.tumor_code
cases.samples.tumor_code_id
cases.samples.tumor_descriptor
cases.samples.updated_datetime
cases.samples.annotations.annotation_id
cases.samples.annotations.case_id
cases.samples.annotations.case_submitter_id
cases.samples.annotations.category
cases.samples.annotations.classification
cases.samples.annotations.created_datetime
cases.samples.annotations.creator
cases.samples.annotations.entity_id
cases.samples.annotations.entity_submitter_id
cases.samples.annotations.entity_type
cases.samples.annotations.legacy_created_datetime
cases.samples.annotations.legacy_updated_datetime
cases.samples.annotations.notes
cases.samples.annotations.state
cases.samples.annotations.status
cases.samples.annotations.submitter_id
cases.samples.annotations.updated_datetime
cases.samples.portions.created_datetime
cases.samples.portions.creation_datetime
cases.samples.portions.is_ffpe
cases.samples.portions.portion_id
cases.samples.portions.portion_number
1.11.1 Field Listing by Endpoint
- 195/232 -
© 2015-2024
Field Name
cases.samples.portions.state
cases.samples.portions.submitter_id
cases.samples.portions.updated_datetime
cases.samples.portions.weight
cases.samples.portions.analytes.a260_a280_ratio
cases.samples.portions.analytes.amount
cases.samples.portions.analytes.analyte_id
cases.samples.portions.analytes.analyte_type
cases.samples.portions.analytes.analyte_type_id
cases.samples.portions.analytes.concentration
cases.samples.portions.analytes.created_datetime
cases.samples.portions.analytes.spectrophotometer_method
cases.samples.portions.analytes.state
cases.samples.portions.analytes.submitter_id
cases.samples.portions.analytes.updated_datetime
cases.samples.portions.analytes.well_number
cases.samples.portions.analytes.aliquots.aliquot_id
cases.samples.portions.analytes.aliquots.amount
cases.samples.portions.analytes.aliquots.analyte_type
cases.samples.portions.analytes.aliquots.analyte_type_id
cases.samples.portions.analytes.aliquots.concentration
cases.samples.portions.analytes.aliquots.created_datetime
cases.samples.portions.analytes.aliquots.source_center
cases.samples.portions.analytes.aliquots.state
cases.samples.portions.analytes.aliquots.submitter_id
cases.samples.portions.analytes.aliquots.updated_datetime
cases.samples.portions.analytes.aliquots.annotations.annotation_id
cases.samples.portions.analytes.aliquots.annotations.case_id
cases.samples.portions.analytes.aliquots.annotations.case_submitter_id
cases.samples.portions.analytes.aliquots.annotations.category
cases.samples.portions.analytes.aliquots.annotations.classification
cases.samples.portions.analytes.aliquots.annotations.created_datetime
cases.samples.portions.analytes.aliquots.annotations.creator
cases.samples.portions.analytes.aliquots.annotations.entity_id
cases.samples.portions.analytes.aliquots.annotations.entity_submitter_id
1.11.1 Field Listing by Endpoint
- 196/232 -
© 2015-2024
Field Name
cases.samples.portions.analytes.aliquots.annotations.entity_type
cases.samples.portions.analytes.aliquots.annotations.legacy_created_datetime
cases.samples.portions.analytes.aliquots.annotations.legacy_updated_datetime
cases.samples.portions.analytes.aliquots.annotations.notes
cases.samples.portions.analytes.aliquots.annotations.state
cases.samples.portions.analytes.aliquots.annotations.status
cases.samples.portions.analytes.aliquots.annotations.submitter_id
cases.samples.portions.analytes.aliquots.annotations.updated_datetime
cases.samples.portions.analytes.aliquots.center.center_id
cases.samples.portions.analytes.aliquots.center.center_type
cases.samples.portions.analytes.aliquots.center.code
cases.samples.portions.analytes.aliquots.center.name
cases.samples.portions.analytes.aliquots.center.namespace
cases.samples.portions.analytes.aliquots.center.short_name
cases.samples.portions.analytes.annotations.annotation_id
cases.samples.portions.analytes.annotations.case_id
cases.samples.portions.analytes.annotations.case_submitter_id
cases.samples.portions.analytes.annotations.category
cases.samples.portions.analytes.annotations.classification
cases.samples.portions.analytes.annotations.created_datetime
cases.samples.portions.analytes.annotations.creator
cases.samples.portions.analytes.annotations.entity_id
cases.samples.portions.analytes.annotations.entity_submitter_id
cases.samples.portions.analytes.annotations.entity_type
cases.samples.portions.analytes.annotations.legacy_created_datetime
cases.samples.portions.analytes.annotations.legacy_updated_datetime
cases.samples.portions.analytes.annotations.notes
cases.samples.portions.analytes.annotations.state
cases.samples.portions.analytes.annotations.status
cases.samples.portions.analytes.annotations.submitter_id
cases.samples.portions.analytes.annotations.updated_datetime
cases.samples.portions.annotations.annotation_id
cases.samples.portions.annotations.case_id
cases.samples.portions.annotations.case_submitter_id
cases.samples.portions.annotations.category
1.11.1 Field Listing by Endpoint
- 197/232 -
© 2015-2024
Field Name
cases.samples.portions.annotations.classification
cases.samples.portions.annotations.created_datetime
cases.samples.portions.annotations.creator
cases.samples.portions.annotations.entity_id
cases.samples.portions.annotations.entity_submitter_id
cases.samples.portions.annotations.entity_type
cases.samples.portions.annotations.legacy_created_datetime
cases.samples.portions.annotations.legacy_updated_datetime
cases.samples.portions.annotations.notes
cases.samples.portions.annotations.state
cases.samples.portions.annotations.status
cases.samples.portions.annotations.submitter_id
cases.samples.portions.annotations.updated_datetime
cases.samples.portions.center.center_id
cases.samples.portions.center.center_type
cases.samples.portions.center.code
cases.samples.portions.center.name
cases.samples.portions.center.namespace
cases.samples.portions.center.short_name
cases.samples.portions.slides.created_datetime
cases.samples.portions.slides.number_proliferating_cells
cases.samples.portions.slides.percent_eosinophil_infiltration
cases.samples.portions.slides.percent_granulocyte_infiltration
cases.samples.portions.slides.percent_inflam_infiltration
cases.samples.portions.slides.percent_lymphocyte_infiltration
cases.samples.portions.slides.percent_monocyte_infiltration
cases.samples.portions.slides.percent_necrosis
cases.samples.portions.slides.percent_neutrophil_infiltration
cases.samples.portions.slides.percent_normal_cells
cases.samples.portions.slides.percent_stromal_cells
cases.samples.portions.slides.percent_tumor_cells
cases.samples.portions.slides.percent_tumor_nuclei
cases.samples.portions.slides.section_location
cases.samples.portions.slides.slide_id
cases.samples.portions.slides.state
1.11.1 Field Listing by Endpoint
- 198/232 -
© 2015-2024
Field Name
cases.samples.portions.slides.submitter_id
cases.samples.portions.slides.updated_datetime
cases.samples.portions.slides.annotations.annotation_id
cases.samples.portions.slides.annotations.case_id
cases.samples.portions.slides.annotations.case_submitter_id
cases.samples.portions.slides.annotations.category
cases.samples.portions.slides.annotations.classification
cases.samples.portions.slides.annotations.created_datetime
cases.samples.portions.slides.annotations.creator
cases.samples.portions.slides.annotations.entity_id
cases.samples.portions.slides.annotations.entity_submitter_id
cases.samples.portions.slides.annotations.entity_type
cases.samples.portions.slides.annotations.legacy_created_datetime
cases.samples.portions.slides.annotations.legacy_updated_datetime
cases.samples.portions.slides.annotations.notes
cases.samples.portions.slides.annotations.state
cases.samples.portions.slides.annotations.status
cases.samples.portions.slides.annotations.submitter_id
cases.samples.portions.slides.annotations.updated_datetime
cases.summary.file_count
cases.summary.file_size
cases.summary.data_categories.data_category
cases.summary.data_categories.file_count
cases.summary.experimental_strategies.experimental_strategy
cases.summary.experimental_strategies.file_count
cases.tissue_source_site.bcr_id
cases.tissue_source_site.code
cases.tissue_source_site.name
cases.tissue_source_site.project
cases.tissue_source_site.tissue_source_site_id
center.center_id
center.center_type
center.code
center.name
center.namespace
1.11.1 Field Listing by Endpoint
- 199/232 -
© 2015-2024
Field Name
center.short_name
downstream_analyses.analysis_id
downstream_analyses.analysis_type
downstream_analyses.created_datetime
downstream_analyses.state
downstream_analyses.submitter_id
downstream_analyses.updated_datetime
downstream_analyses.workflow_end_datetime
downstream_analyses.workflow_link
downstream_analyses.workflow_start_datetime
downstream_analyses.workflow_type
downstream_analyses.workflow_version
downstream_analyses.output_files.access
downstream_analyses.output_files.created_datetime
downstream_analyses.output_files.data_category
downstream_analyses.output_files.data_format
downstream_analyses.output_files.data_type
downstream_analyses.output_files.error_type
downstream_analyses.output_files.experimental_strategy
downstream_analyses.output_files.file_id
downstream_analyses.output_files.file_name
downstream_analyses.output_files.file_size
downstream_analyses.output_files.file_state
downstream_analyses.output_files.md5sum
downstream_analyses.output_files.platform
downstream_analyses.output_files.revision
downstream_analyses.output_files.state
downstream_analyses.output_files.state_comment
downstream_analyses.output_files.submitter_id
downstream_analyses.output_files.updated_datetime
index_files.access
index_files.created_datetime
index_files.data_category
index_files.data_format
index_files.data_type
1.11.1 Field Listing by Endpoint
- 200/232 -
© 2015-2024
Field Name
index_files.error_type
index_files.experimental_strategy
index_files.file_id
index_files.file_name
index_files.file_size
index_files.file_state
index_files.md5sum
index_files.platform
index_files.revision
index_files.state
index_files.state_comment
index_files.submitter_id
index_files.updated_datetime
metadata_files.access
metadata_files.created_datetime
metadata_files.data_category
metadata_files.data_format
metadata_files.data_type
metadata_files.error_type
metadata_files.file_id
metadata_files.file_name
metadata_files.file_size
metadata_files.file_state
metadata_files.md5sum
metadata_files.state
metadata_files.state_comment
metadata_files.submitter_id
metadata_files.type
metadata_files.updated_datetime
1.11.1 Field Listing by Endpoint
- 201/232 -
© 2015-2024
Annotation Fields
Field Name
annotation_id
case_id
case_submitter_id
category
classification
created_datetime
entity_id
entity_submitter_id
entity_type
legacy_created_datetime
legacy_updated_datetime
notes
state
status
submitter_id
updated_datetime
project.code
project.dbgap_accession_number
project.disease_type
project.name
project.primary_site
project.program.dbgap_accession_number
project.program.name
project.program.program_id
project.project_id
project.released
project.state
1.11.1 Field Listing by Endpoint
- 202/232 -
© 2015-2024
1.11.2 Field Group Listing by Endpoint
Projects Field Groups
Field Group Name
program
summary
summary.data_categories
summary.experimental_strategies
1.11.2 Field Group Listing by Endpoint
- 203/232 -
© 2015-2024
Cases Field Groups
1.11.2 Field Group Listing by Endpoint
- 204/232 -
© 2015-2024
Field Group Name
annotations
demographic
diagnoses
diagnoses.treatments
exposures
family_histories
files
files.analysis
files.analysis.input_files
files.analysis.metadata
files.analysis.metadata.read_groups
files.analysis.metadata.read_groups.read_group_qcs
files.archive
files.cases
files.cases.annotations
files.cases.demographic
files.cases.diagnoses
files.cases.diagnoses.treatments
files.cases.exposures
files.cases.family_histories
files.cases.files
files.cases.project
files.cases.project.program
files.cases.samples
files.cases.samples.annotations
files.cases.samples.portions
files.cases.samples.portions.analytes
files.cases.samples.portions.analytes.aliquots
files.cases.samples.portions.analytes.aliquots.annotations
files.cases.samples.portions.analytes.aliquots.center
files.cases.samples.portions.analytes.annotations
files.cases.samples.portions.annotations
files.cases.samples.portions.center
files.cases.samples.portions.slides
files.cases.samples.portions.slides.annotations
1.11.2 Field Group Listing by Endpoint
- 205/232 -
© 2015-2024
Field Group Name
files.cases.summary
files.cases.summary.data_categories
files.cases.summary.experimental_strategies
files.cases.tissue_source_site
files.center
files.downstream_analyses
files.downstream_analyses.output_files
files.index_files
files.metadata_files
project
project.program
samples
samples.annotations
samples.portions
samples.portions.analytes
samples.portions.analytes.aliquots
samples.portions.analytes.aliquots.annotations
samples.portions.analytes.aliquots.center
samples.portions.analytes.annotations
samples.portions.annotations
samples.portions.center
samples.portions.slides
samples.portions.slides.annotations
summary
summary.data_categories
summary.experimental_strategies
tissue_source_site
1.11.2 Field Group Listing by Endpoint
- 206/232 -
© 2015-2024
Files Field Groups
1.11.2 Field Group Listing by Endpoint
- 207/232 -
© 2015-2024
Field Group Name
analysis
analysis.input_files
analysis.metadata
analysis.metadata.read_groups
analysis.metadata.read_groups.read_group_qcs
annotations
archive
associated_entities
cases
cases.annotations
cases.demographic
cases.diagnoses
cases.diagnoses.treatments
cases.exposures
cases.family_histories
cases.files
cases.project
cases.project.program
cases.samples
cases.samples.annotations
cases.samples.portions
cases.samples.portions.analytes
cases.samples.portions.analytes.aliquots
cases.samples.portions.analytes.aliquots.annotations
cases.samples.portions.analytes.aliquots.center
cases.samples.portions.analytes.annotations
cases.samples.portions.annotations
cases.samples.portions.center
cases.samples.portions.slides
cases.samples.portions.slides.annotations
cases.summary
cases.summary.data_categories
cases.summary.experimental_strategies
cases.tissue_source_site
center
1.11.2 Field Group Listing by Endpoint
- 208/232 -
© 2015-2024
Annotations Field Groups
GDC Conventions Supplemental
| Field Group Name | | --- | --- | | File size | Listed in bytes | | Submitter id | String supplied by submitter | | Datetime | Combination of
date and time of day in the form [-]CCYY-MM-DDThh:mm:ss |
| Id | GDC supplied UUID ID |
Field Group Name
downstream_analyses
downstream_analyses.output_files
index_files
metadata_files
Field Group Name
project
project.program
1.11.2 Field Group Listing by Endpoint
- 209/232 -
© 2015-2024
1.12 Appendix B: Key Terms
The following table provides definitions and explanations for terms and acronyms relevant to the content presented within this
document.
Term Definition
ACL Access Control List
API Application Programming Interface
BAM Bidirectional Associative Memory
BCR Biospecimen Core Resource
CSV Comma Seperated Values
DCC Data Coordinating Center
eRA Electronic Research Administration
GDC Genomic Data Commons
HTTP Hypertext Transfer Protocol
IDE Integrated Development Environment
JSON JavaScript Object Notation
MAGE-TAB Microarray Gene Expression - Tabular format
NCI National Cancer Institute
NIH National Institutes of Health
Op Operations
REST Representational State Transfer
TARGET Therapeutically Applicable Research to Generate Effective Treatments
TCGA The Cancer Genome Atlas
TSV Tab Seperated Values
UUID Universally Unique Identifier
URL Universal Resource Locator
XML Extensible Markup Language
1.12 Appendix B: Key Terms
- 210/232 -
© 2015-2024
1.13 Appendix C: Format of Submission Requests and Responses
Format of Submission Request
The general format of JSON objects submitted to the GDC API is as follows:
The request must specify either an id or a submitter_id .
id : A string specifying the id of the node that the user is creating or updating. This is the persistent GDC UUID4 for the node. If
it is preferred to refer to the node using a custom id, users can do so with the submitter_id field (described below).
submitter_id : A string specifying the custom id of the object the user is creating or updating. This is not the official GDC ID for the
node.
<properties> : These key-value pairs will be applied to properties on the referenced node.
<relationship_name> : A JSON object that specifies a relationship (link) between the node and other nodes. Links are typically
established using the submitter_id or id of the neighboring node.
Format of API Response to a Submission Request
The following fields are included in all API responses to submission requests.
cases_related_to_created_entities_count : Number of cases related to the created entities.
cases_related_to_updated_entities_count : Number of cases related to the updated entities.
code : The HTTP status code of the response message.
created_entity_count : Number of entities created.
entities : A list of entities of the form:
{
"type": string,
"id": string,
"submitter_id": string,
"<properties>": any type,
"<relationship_name>": [
{
"id": string,
},
...
]
}
{
"cases_related_to_created_entities_count": int,
"cases_related_to_updated_entities_count": int,
"code": int,
"created_entity_count": int,
"entities": [entities],
"entity_error_count": int,
"message": string,
"success": boolean,
"transaction_id": string,
"transactional_error_count": int,
"transactional_errors": [transactional_errors],
"updated_entity_count": int
}
{
"action": string,
"errors": [entity_errors],
"id": string,
"related_cases": [object],
"type": string,
"unique_keys": [unique_keys],
"valid": boolean,
"warnings": [object]
}
1.13 Appendix C: Format of Submission Requests and Responses
- 211/232 -
© 2015-2024
entity_errors
: A list of errors that occurred while parsing, validating, or performing a CRUD operation on a specific entity. Entity
errors are of the form:
unique_keys
: Properties, or combinations of properties, that can be used to uniquely identify the node in the GDC. Unique_keys are
of the form:
entity_error_count : Number of entities that were not successful.
message : A human-readable message describing the transaction.
success : A boolean value stating whether the transaction was successful. If the value is False, then no changes will be made to the
database.
transaction_id : A string specifying the transaction id.
transactional_error_count : Number of transactional errors that occurred.
transactional_errors : A list of transactional errors that have occurred. These errors are errors that are not specific to an individual
entity. Transactional errors are of the form:
updated_entity_count : Number of existing entities updated by the transaction.
Error Types
EntityNotFoundError A referenced entity was not found among existing entities and entities specified in the transaction.
MissingPropertyError A required property was not provided.
ValidationError A provided property did not pass a validation test.
1.13.1 Status Messages
API responses will contain a status for each entity specified in the request:
success : The desired transaction was sucessful and the entity's state was modified in the GDC.
valid : The desired transaction was not sucessful, but the trasaction was not aborted because of this entity.
error : The desired transaction was not sucessful, and the transaction was aborted because of this entity. This entity did not pass
validation or an internal error occured when attempting to complete the transaction. The error state will be accompanied by a list
of errors recorded about the entity (see label-error-messages).
Note: GDC API requests are transactional. An error with processing a node specified in the transaction will abort the transaction
and will result in no changes being applied for any node involved in the transaction.
{
"keys": [string],
"message": string
}
{
"project_id": string,
"submitter_id": string
}
{
"message": string
}
1.13.1 Status Messages
- 212/232 -
© 2015-2024
1.14 API Release Notes
1.14 API Release Notes
- 213/232 -
© 2015-2024
Version Date
v7.4.1 July 30, 2024
v7.3.0 June 26, 2024
v4.0.0 July 31, 2023
v3.28.0 May 11, 2023
v3.5.0 July 8, 2022
v3.3.0 May 17, 2021
v3.0.0 August 14, 2020
v2.1.2 May 7, 2020
v2.1.0 March 10, 2020
v2.0.0 January 30, 2020
v1.23.0 November 6, 2019
v1.22.0 July 31, 2019
v1.21.0 June 5, 2019
v1.20.0 April 17, 2019
v1.19.0 February 20, 2019
v1.18.0 December 18, 2018
v1.17.0 November 7, 2018
v1.16.0 September 27, 2018
v1.15.0 August 23, 2018
v1.14.1 May 21, 2018
v1.14.0 April 23, 2018
v1.13.0 February 15, 2018
v1.12.0 December 21, 2017
v1.11.0 November 16, 2017
v1.10.0 August 22, 2017
v1.9.0 June 29, 2017
v1.8.0 May 9, 2017
v1.7.1 March 16, 2017
v1.5.0 October 31, 2016
v1.4.0 September 23, 2016
v1.3.1 September 7, 2016
v1.2.0 August 9, 2016
v1.1.0 May 25, 2016
v1.0.1 May 16, 2016
1.14 API Release Notes
- 214/232 -
© 2015-2024
1.14.1 v7.4.2
• GDC Product: Application Programming Interface (API)
• Release Date: July 30, 2024
New Features and Changes
• The API indices will include fields from the "other clinical attribute" entity types. This will be visible in the next data release.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Some fields may be repeated in the API or data portal due to being in a transitional states. As a workaround, select all of the
fields of interest, and the results will demonstrate which are currently populated.
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.2 v7.3.0
• GDC Product: Application Programming Interface (API)
• Release Date: June 26, 2024
New Features and Changes
• The GDC submission API now supports the PATCH method, which allow users to upload without required fields while updating
already-existing entities.
• The gene expression API is now available to be queried by users. See the Gene Expression API documentation for more
information.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.3 v4.0.0
• GDC Product: Application Programming Interface (API)
• Release Date: July 31, 2023
1.14.1 v7.4.2
- 215/232 -
© 2015-2024
New Features and Changes
• The GDC API no longer supports download of Legacy Archive files.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.4 v3.28.0
• GDC Product: Application Programming Interface (API)
• Release Date: May 11, 2023
New Features and Changes
• The /legacy/files endpoint has been deprecated and is no longer available.
• Features to support Data Portal bugfixes were added.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.5 v3.5.0
• GDC Product: Application Programming Interface (API)
• Release Date: July 8, 2022
New Features and Changes
• Features to support Data Portal performance were added.
Bugs Fixed Since Last Release
• None
1.14.4 v3.28.0
- 216/232 -
© 2015-2024
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.6 v3.3.0
• GDC Product: Application Programming Interface (API)
• Release Date: May 17, 2021
New Features and Changes
• Features to better support batch tracking for submitted data were added.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.7 v3.0.0
• GDC Product: Application Programming Interface (API)
• Release Date: August 14, 2020
New Features and Changes
• Enhancements were made to increase performance.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.8 v2.1.2
• GDC Product: Application Programming Interface (API)
1.14.6 v3.3.0
- 217/232 -
© 2015-2024
• Release Date: May 7, 2020
New Features and Changes
• An update to improve usability in the homepage quicksearch
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.9 v2.1.0
• GDC Product: Application Programming Interface (API)
• Release Date: March 10, 2020
New Features and Changes
• New data dictionary changes.
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.10 v2.0.0
• GDC Product: Application Programming Interface (API)
• Release Date: January 30, 2020
New Features and Changes
• API code now uses Python 3.
Bugs Fixed Since Last Release
• None
1.14.9 v2.1.0
- 218/232 -
© 2015-2024
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.11 v1.23.0
• GDC Product: Application Programming Interface (API)
• Release Date: November 6, 2019
New Features and Changes
• QC Tests added for Submission
• BAM slicing is now supported for unmapped reads
• API now includes data from molecular_test and follow_up nodes. This impacts what is displayed on the GDC Data Portal
• Better handling of concurrent transactions
• CIViC annotations now included on the ssms endpoint. You can read more about CIViC annotations here
Bugs Fixed Since Last Release
• Fixed API memory leak
• Fixed data offset issue returned by clinical.tar endpoint
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.12 v1.22.0
• GDC Product: Application Programming Interface (API)
• Release Date: July 31, 2019
1.14.11 v1.23.0
- 219/232 -
© 2015-2024
New Features and Changes
• Updated BCR Clinical XML parser code to support future indexing of additional clinical data. Parser code can be found here
• Added a mapping for:
• ann_arbor_b_symptoms
• ann_arbor_extranodal_involvement
• ajcc_pathologic_t
• ajcc_pathologic_n
• ajcc_pathologic_m
• ajcc_clinical_t
• ajcc_clinical_n
• ajcc_clinical_m
• ajcc_staging_system_edition
• figo_stage
• ajcc_clinical_stage
• primary_gleason_grade
• secondary_gleason_graade
• igcccg_stage
• masaoka_stage
• Updated the mapping for:
• primary_diagnosis , morphology , tissue_or_organ_of_origin , and site_of_resection_or_biopsy
Bugs Fixed Since Last Release
• Fixed a bug preventing multipart uploads
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.13 v1.21.0
• GDC Product: Application Programming Interface (API)
• Release Date: June 5, 2019
New Features and Changes
• Mutation indexer update to accommodate data model changes
• Updates to when in the release cycle downloaders and submitters have access to files
Bugs Fixed Since Last Release
• None
1.14.13 v1.21.0
- 220/232 -
© 2015-2024
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.14 v1.20.0
• GDC Product: Application Programming Interface (API)
• Release Date: April 17, 2019
New Features and Changes
• Disallowed creation of multiple file versions in the same data release
• Improved API concurrency performance and addressed random failures/4XX/5XX responses
• Improved API/Portal performances for querying large sets of data from the Elasticsearch indices
• Updated BCR Clinical XML parser code to support future indexing of additional clinical data. Parser code can be found here
• Updated the mapping for:
•
days_to_death
• days_to_birth
• vital_status
• prior_malignancy and synchronous_malignancy
• Added a mapping for:
• pack_years_smoked
• prior_treatment
• age_at_index
• days_to_diagnosis
• icd_10_code
• year_of_diagnosis
• Remove calculation for:
• cigarettes_per_day
• year_of_birth
• year_of_death
• bmi
• Updated XML Parser to pull the most Up-to-Date Survival Information
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
1.14.14 v1.20.0
- 221/232 -
© 2015-2024
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.15 v1.19.0
• GDC Product: Application Programming Interface (API)
• Release Date: February 20, 2019
New Features and Changes
• Added API features to support controlled access DAVE
• Updated API query endpoints to handle filtering of queries based on tokens
• Created login notification Endpoint
• Added hashing and logging for similar ES queries
Bugs Fixed Since Last Release
• Fixed bug where quick search ES query grows with each request
• Fixed bug where new file versions could be created when exactly the same existing metadata is uploaded
• Fixed bug where submitting to specific projects produced error that data already existed
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.16 v1.18.0
• GDC Product: Application Programming Interface (API)
• Release Date: December 18, 2018
New Features and Changes
• Update to auth for GDC Pre-Release Data Portal
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.17 v1.17.0
• GDC Product: Application Programming Interface (API)
1.14.15 v1.19.0
- 222/232 -
© 2015-2024
• Release Date: November 7, 2018
New Features and Changes
• Created new index cnv_centric
• Created new index cnv_occurrence_centric
• Created new REST API endpoints for CNV
• Created mapping from aliquot to case for occurrence on cnv_centric
• Created new graphql endpoints for CNV
• Updated index case_centric to add cnv
• Updated index gene_centric to add cnv
Bugs Fixed Since Last Release
• Fixed bug to prevent users from deleting files in state submitted or released
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.18 v1.16.0
• GDC Product: Application Programming Interface (API)
• Release Date: September 27, 2018
New Features and Changes
• Tissue_type is now parsed from the BCR Biospecimen submission
Bugs Fixed Since Last Release
• Re-attach the /files path to the legacy blueprints in gdcapi
• Fix Internal Server Error when exporting JSON in Data Portal
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.19 v1.15.0
• GDC Product: Application Programming Interface (API)
• Release Date: August 23, 2018
1.14.18 v1.16.0
- 223/232 -
© 2015-2024
New Features and Changes
• Added support for file versioning
• Added new API endpoints in support of versioning: history, files/versions, and files/versions/manifest
• Updated the submit and release process
• Created admin endpoint to allow for modifying file and project flags and states
• Populate version and release information for all existing files
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.20 v1.14.1
• GDC Product: Application Programming Interface (API)
• Release Date: May 21, 2018
New Features and Changes
• None
Bugs Fixed Since Last Release
• Update to XML submission to correctly import biospecimen relationnships
• GraphQL submission queries return incorrect information
Known Issues and Workarounds
• The error message for not including a token is incorrect for controlled access API requests (e.g. bam slicing). It states that your
token is invalid, but it should request that a token be supplied.
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.21 v1.14.0
• GDC Product: Application Programming Interface (API)
• Release Date: April 23, 2018
New Features and Changes
• Updated support of BCR XML submission for Next Generation Cancer Models
1.14.20 v1.14.1
- 224/232 -
© 2015-2024
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.22 v1.13.0
• GDC Product: Application Programming Interface (API)
• Release Date: February 15, 2018
New Features and Changes
• Reduced number of submission portal timeouts by optimizing graphql API requests
Bugs Fixed Since Last Release
• Fixed bug preventing submission of clinical data via BCR XML
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.23 v1.12.0
• GDC Product: Application Programming Interface (API)
• Release Date: December 21, 2017
New Features and Changes
• None
Bugs Fixed Since Last Release
• Updated submit project button on submission portal to work more quickly for projects with large numbers of nodes
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.22 v1.13.0
- 225/232 -
© 2015-2024
1.14.24 v1.11.0
• GDC Product: Application Programming Interface (API)
• Release Date: November 16, 2017
New Features and Changes
• Added support for histogram aggregation for numeric fields
Bugs Fixed Since Last Release
• None
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.25 v1.10.0
• GDC Product: Application Programming Interface (API)
• Release Date: August 22, 2017
New Features and Changes
• Longitudinal clinical data can now be submitted to the GDC
• Created new entities and reorganized the location of many properties in the GDC Dictionary. A list of deprecated properties and
their new locations can be found here. Note that the deprecated properties still contain all information that they previously did.
In a later release we will map the data from the old location to the new. Eventually, we will suspend submission to the old
properties and will remove them entirely from the GDC.
• GDC Data Dictionary Changes Details
• Created follow_up entity to support longitudinal clinical data
• Deprecated clinical test entity
• Modified acceptable values for Read Group properties
• Modified Diagnosis entity
• Modified Treatment entity
• Modified Demographic entity
• Modified Case entity
• Added new tumor code, tumor id, and sample types to Sample entity to support OCG
• Added property
days_to_diagnosis to Diagnosis entity
• Created Somatic Mutation Index entity
• Updated CaDSR CDE links in data dictionary
• Added new sample type tumor to sample entity
• Made classification_of_tumor on diagnosis entity non-required
• Added support for FM-AD to Genomic Profile Harmonization Workflow entity
• Added data type Gene Level Copy Number Scores to Copy Number Segment entity
1.14.24 v1.11.0
- 226/232 -
© 2015-2024
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.26 v1.9.0
• GDC Product: Application Programming Interface (API)
• Release Date: June 29, 2017
New Features and Changes
• Updated ability to search data based on genes and mutations have been released. Discussion of the new endpoints and their use
can be found in the Data Portal User Guide. These feature are limited to those projects for which the GDC contains open-access
MAF files.
• API request parameter from now returns first record when from=0 . Previously, from=1 was the first record. from=0 is now the
default.
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.27 v1.8.0
• GDC Product: Application Programming Interface (API)
• Release Date: May 9, 2017
New Features and Changes
• Users can now control whether a set of files will be compressed or not when downloading. For further details see the API User
Guide.
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.28 v1.7.1
• GDC Product: Application Programming Interface (API)
• Release Date: March 16, 2017
1.14.26 v1.9.0
- 227/232 -
© 2015-2024
New Features and Changes
• Submission: Due to Data Dictionary updates new submission templates may be required for users submitting JSON and TSV
formats
• Submission: Entities in submitted state (assigned when the project has been submitted) cannot be deleted.
• Submission: When attempting to delete an entity that has child entities not specified in the request, an error message is
generated that will include all of the child entities' UUIDs.
• Submission: Entities associated with files uploaded to the GDC object store cannot be deleted until the associated file has been
deleted.
• Re-enable Review, Submit, and Release functions for submission
• GDC Data Dictionary Changes
• Added "submittable" property to all entities
• Changed Read Group to category biospecimen
• Added many new clinical properties available for submission
• Added sample codes from Office of Cancer Genomics (OCG) to analyte and aliquot
• Slides can now be attached to sample rather than just portion
•
sample_type_id is no longer required when submitting sample entities
• analyte_type_id is no longer required when submitting aliquot and analyte entities
• Clinical Test Entity is created for storing results of a variety of potential clinical tests related to the diagnosis -
• Genomic Profiling Report entity created for storing particular derived sequencing results
• Structural Variation entity created
• Project entity includes new field "Intended Release Date"
• Project entity includes new field "Releasable"
Bugs Fixed Since Last Release
• Fixed bug where boolean properties were not accepted with TSV submission
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.29 v1.5.0
• GDC Product: Application Programming Interface (API)
• Release Date: October 31, 2016
New Features and Changes
• API responds with an error when the request specifies an unsupported combination of filters and facets .
• In TSV submissions, trailing and leading whitespace, including non-ASCII whitespace characters, are stripped from property
names and values.
• For released projects, any updates to previously submitted entities (i.e. "state": "submitted" ) will be included in the following
GDC data release.
1.14.29 v1.5.0
- 228/232 -
© 2015-2024
• Performance improvements for manifest generation.
Bugs Fixed Since Last Release
• Uploading certain unsupported metadata files caused the associated submission transactions to remain stuck in pending state.
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.30 v1.4.0
• GDC Product: Application Programming Interface (API)
• Release Date: September 23, 2016
New Features and Changes
• Submission transaction log includes additional information to assist in tracking.
• Submission project state transitions are disabled temporarily while project release features are being improved.
• GDC data dictionary changes:
• The submittable property was added to all entity types in the GDC data model. It indicates whether the entity type can be
submitted by users.
• Category of Read Group entities in the GDC Data Model has changed from data_bundle to biospecimen .
• Analyte entities support an expanded set of analyte_type values.
Bugs Fixed Since Last Release
• None to report
Known Issues and Workarounds
• API search & retrieval queries that do not include a sort parameter may return results in different order each time they are
executed. This is a particular problem for paginated responses (i.e. responses to queries for which the number of results is
greater than the size parameter).
• Workaround: Include a sort parameter in API search & retrieval queries.
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.31 v1.3.1
• GDC Product: Application Programming Interface (API)
• Release Date: September 7, 2016
1.14.30 v1.4.0
- 229/232 -
© 2015-2024
New Features and Changes
• Successful _dry_run submission transactions can be committed to the GDC data model without having to re-upload metadata.
The transactions can also be closed to prevent them from being committed in the future.
• Submission transactions can be submitted in asynchronous mode. In this mode, the GDC API will issue an immediate
acknowledgement of the transaction, along with the transaction_id . The status of the transaction can be verified by the user at a
later time by specifying the transaction_id . Users submitting large transactions may find this mode helpful.
• New submission transaction properties can be queried with GraphQL
• GDC Data Dictionary changes:
• Clinical Supplement entities can have data_format set to OMF.
• Biospecimen Supplement entities can have data_format set to SSF or PPS.
• Read group instrument_model can be set to "Illumina HiSeq 4000".
• Category of Slide entities in the GDC Data Model has changed from data_bundle to biospecimen .
Bugs Fixed Since Last Release
• Incorrect BMI calculation in the import of BCR XML files.
Known Issues and Workarounds
• API search & retrieval queries that do not include a sort parameter may return results in different order each time they are
executed. This is a particular problem for paginated responses (i.e. responses to queries for which the number of results is
greater than the size parameter).
• Workaround: Include a sort parameter in API search & retrieval queries.
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.32 v1.2.0
• GDC Product: Application Programming Interface (API)
• Release Date: August 9, 2016
New Features and Changes
• Tarballs generated by the data endpoint in response to multi-file data download requests now include a folder structure that
puts each file in a folder whose name is the file's UUID.
• UUIDs in clinical XML files are no longer treated in a case-sensitive way by the submission endpoint.
• Improved performance of submission endpoint for transactions that include many cases.
• Speed improvements for the submission endpoint.
• BCR XML is no longer validated against its XSD at submission.
Bugs Fixed Since Last Release
• Fixed handling of POST requests to address problems with cart functionality in older versions of Firefox
• Files of category related_files can now be downloaded from the data endpoint.
• Allowed submission by projects in certain dbGaP registration states that were previously blocked.
1.14.32 v1.2.0
- 230/232 -
© 2015-2024
Known Issues and Workarounds
• API search & retrieval queries that do not include a sort parameter may return results in different order each time they are
executed. This is a particular problem for paginated responses (i.e. responses to queries for which the number of results is
greater than the size parameter).
• Workaround: Include a sort parameter in API search & retrieval queries.
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.33 v1.1.0
• GDC Product: Application Programming Interface (API)
• Release Date: May 25, 2016
New Features and Changes
• BAM index files (.bai) are now automatically downloaded with parent BAM.
Bugs Fixed Since Last Release
• None to report
Bugs Fixed Since Last Release
• Sorting by file submitter_id no longer causes an internal server error
• BAM index files are now included with harmonized BAM files
• Certain very long API requests will time out. It is recommended to break up into a series of smaller requests.
Known Issues and Workarounds
• Fields are not counted as missing if parent field is also missing. This may occur with queries of nested fields in the Data Portal
Advanced Search or an API query using a filter. This behavior could impact results reported using search parameters of "IS
MISSING" or "NOT MISSING".
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.34 v1.0.1
• GDC Product: Application Programming Interface (API)
• Release Date: May 16, 2016
New Features and Changes
• HTTP interface that uses JSON as the primary data exchange format
• Programmatic access to functionality provided by GDC Data and Submission portals, via projects , cases , files , annotations ,
data , slicing , status , and submission endpoints
• Programmatic access to GDC Legacy Archive via legacy endpoint
• Token-based authentication for secure access to controlled data and to submission functionality
1.14.33 v1.1.0
- 231/232 -
© 2015-2024
• RESTful search that supports simple and complex queries via filters , fields , and facets parameters, and project , files ,
cases , and annotations endpoints.
• Search results can be sorted using sort parameter, paginated using size and from parameters, and output in JSON, TSV, and
XML using format and pretty parameters.
• _mapping endpoint enables user discovery of fields available for data search and retrieval operations
• Support for downloading of individual files and of archives containing multiple files
• Generation of download and upload manifests for use with the GDC Data Transfer Tool
• BAM slicing functionality for downloading part(s) of a BAM file specified using chromosomal coordinates or HGNC gene names
• Transactional submission system that links individual data elements according to a graph-based GDC Data Model
• Two data entity identifiers: UUIDs, which are consistent across GDC, and Submitter IDs, for compatibility with submitters'
tracking systems
Bugs Fixed Since Last Release
• None to report
Known Issues and Workarounds
• Use of non-ascii characters in token passed to Data Transfer Tool will produce incorrect error message "Internal server error:
Auth service temporarily unavailable".
• Use of a decimal in an integer search field produces unexpected error.
• Certain very large API requests will time out. It is recommended to break up very large requests into a series of smaller
requests.
1.14.34 v1.0.1
- 232/232 -
© 2015-2024