Additional Examples
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.
curl 'https://api.gdc.cancer.gov/projects?from=0&size=5&sort=name: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": "TARGET-ALL-P1",
"primary_site": [
"Hematopoietic and reticuloendothelial systems"
],
"dbgap_accession_number": "phs000463",
"project_id": "TARGET-ALL-P1",
"disease_type": [
"Lymphoid Leukemias"
],
"name": "Acute Lymphoblastic Leukemia - Phase I",
"releasable": true,
"state": "open",
"released": true
},
{
"id": "TARGET-ALL-P2",
"primary_site": [
"Hematopoietic and reticuloendothelial systems"
],
"dbgap_accession_number": "phs000464",
"project_id": "TARGET-ALL-P2",
"disease_type": [
"Lymphoid Leukemias"
],
"name": "Acute Lymphoblastic Leukemia - Phase II",
"releasable": true,
"state": "open",
"released": true
},
{
"id": "TARGET-ALL-P3",
"primary_site": [
"Unknown",
"Hematopoietic and reticuloendothelial systems"
],
"dbgap_accession_number": null,
"project_id": "TARGET-ALL-P3",
"disease_type": [
"Myeloid Leukemias",
"Not Applicable",
"Lymphoid Leukemias",
"Leukemias, NOS"
],
"name": "Acute Lymphoblastic Leukemia - Phase III",
"releasable": true,
"state": "open",
"released": true
},
{
"id": "TARGET-AML",
"primary_site": [
"Hematopoietic and reticuloendothelial systems",
"Unknown"
],
"dbgap_accession_number": "phs000465",
"project_id": "TARGET-AML",
"disease_type": [
"Not Applicable",
"Myeloid Leukemias"
],
"name": "Acute Myeloid Leukemia",
"releasable": true,
"state": "open",
"released": true
}
],
"pagination": {
"count": 5,
"total": 86,
"size": 5,
"from": 0,
"sort": "None",
"page": 1,
"pages": 18
}
},
"warnings": {}
}
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.
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": {}
}
Cases Endpoint Examples
This example is a query for cases contained in GDC. It returns only the first five files.
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",
"sample_ids": [
"21456849-38a9-4190-9ece-ed69b3c24fda",
"6ee6d239-2af6-41cd-bc32-c5cdaf7742b0"
],
"portion_ids": [
"484b40d5-d77c-4e6f-9e80-1ef27ffbc8a5",
"fdc56e67-52ab-44fd-823a-5a3124876ff7"
],
"submitter_portion_ids": [
"TCGA-VR-AA4G-10A-01",
"TCGA-VR-AA4G-01A-11"
],
"created_datetime": null,
"slide_ids": [
"e950eba2-7d6e-4ffd-a2d5-e0eb6486848a"
],
"state": "live",
"aliquot_ids": [
"db6beed3-a5a2-469f-8dc8-00d838c1f37f",
"f5db4d36-034b-429b-a7be-26a872b702ee",
"16421a96-b843-4f7e-9f7c-64d2fb5b2a25",
"5d938cb5-7064-40bc-877d-57faa94c3333",
"d231404d-ece5-43c0-a8a3-e9f294ceb777",
"8c77dc3e-2ea3-4626-88f5-e74f242bedf3",
"993624d4-1c28-41a5-a0b6-094a0e442c36",
"105a18c9-df7e-4573-b1a2-6a987e57d553",
"af81c3bb-3b9e-41cb-b85a-b55c6437d05b",
"38938066-5fd9-415c-b00e-65efff14085e",
"20139afe-ad04-4571-b779-0c4a51e74ada"
],
"primary_site": "Esophagus",
"submitter_aliquot_ids": [
"TCGA-VR-AA4G-10A-01W-A44M-09",
"TCGA-VR-AA4G-01A-11D-A37B-01",
"TCGA-VR-AA4G-01A-11D-A37D-05",
"TCGA-VR-AA4G-10A-01D-A37F-09",
"TCGA-VR-AA4G-01A-11D-A37R-26",
"TCGA-VR-AA4G-01A-11R-A37J-13",
"TCGA-VR-AA4G-01A-11R-A37I-31",
"TCGA-VR-AA4G-01A-11D-A37C-09",
"TCGA-VR-AA4G-10A-01D-A37R-26",
"TCGA-VR-AA4G-10A-01D-A37E-01",
"TCGA-VR-AA4G-01A-11W-A44L-09"
],
"submitter_sample_ids": [
"TCGA-VR-AA4G-01A",
"TCGA-VR-AA4G-10A"
],
"submitter_slide_ids": [
"TCGA-VR-AA4G-01A-01-TS1"
]
},
{
"updated_datetime": "2017-03-04T16:39:19.244769-06:00",
"submitter_analyte_ids": [
"TCGA-D1-A174-01A-11D",
"TCGA-D1-A174-01A-11W",
"TCGA-D1-A174-10A-01D",
"TCGA-D1-A174-10A-01W",
"TCGA-D1-A174-01A-11R"
],
"analyte_ids": [
"96203028-f824-4a90-9758-22340285062c",
"f4878e33-b773-43b5-83a5-9fd8e539e668",
"8627ccd0-0575-4d03-b589-ca45642d523d",
"1183f7c6-992d-4084-946e-adce7c52f9cc",
"5343f6a8-8ac2-4446-ace5-a27d21e76844"
],
"submitter_id": "TCGA-D1-A174",
"case_id": "fc7315b0-9f48-4206-b197-2268c0518eb4",
"id": "fc7315b0-9f48-4206-b197-2268c0518eb4",
"disease_type": "Uterine Corpus Endometrial Carcinoma",
"sample_ids": [
"df9a1f44-9b3f-48b2-96af-54aaabdfd243",
"ad5a9cb6-b3f9-4651-b6d1-13c78010bd88"
],
"portion_ids": [
"79dd516c-bae3-4f6e-b4cb-901de030acb7",
"6e55e6d9-902f-439b-b6f1-ca296c123fd3"
],
"submitter_portion_ids": [
"TCGA-D1-A174-01A-11",
"TCGA-D1-A174-10A-01"
],
"created_datetime": null,
"slide_ids": [
"7602727e-b46d-40fc-bd03-5ccf631041f8"
],
"state": "live",
"aliquot_ids": [
"5c15542b-cd63-44b5-b278-e211410fb0aa",
"d661cfb9-248a-49e6-b0db-865ca257e8dc",
"83bd3bdb-9bd3-46fa-888c-f6f5efec530f",
"c46551c9-c0d0-4140-8d0a-946b53e504e2",
"96b511df-3a69-4168-908c-662060b4f976",
"0182d4e1-f835-46b5-a8f0-53decf5868de",
"e9563a06-0b86-4986-976e-43d4040f1d61",
"6bb2de6e-5b85-4e97-a930-1f2c6bf663a1",
"f6ee5558-a1b6-4b11-8f48-c17186fff39a",
"67f6f0d9-6581-4946-a9c7-a6629da86888",
"39e9a948-054a-4b50-b108-7d7aee686363",
"ddb4ca26-655d-4bdc-a00d-7caf26cadafe"
],
"primary_site": "Uterus",
"submitter_aliquot_ids": [
"TCGA-D1-A174-01A-11D-A12F-02",
"TCGA-D1-A174-01A-01D-YYYY-23",
"TCGA-D1-A174-01A-11W-A139-09",
"TCGA-D1-A174-10A-01W-A139-09",
"TCGA-D1-A174-01A-11D-A12K-05",
"TCGA-D1-A174-10A-01D-A12F-02",
"TCGA-D1-A174-10A-01D-A12G-01",
"TCGA-D1-A174-01A-11R-A12I-07",
"TCGA-D1-A174-01A-11D-A12J-09",
"TCGA-D1-A174-10A-01D-A12J-09",
"TCGA-D1-A174-01A-11R-A12H-13",
"TCGA-D1-A174-01A-11D-A12G-01"
],
"submitter_sample_ids": [
"TCGA-D1-A174-01A",
"TCGA-D1-A174-10A"
],
"submitter_slide_ids": [
"TCGA-D1-A174-01A-01-TS1"
]
},
{
"updated_datetime": "2017-03-04T16:39:19.244769-06:00",
"submitter_analyte_ids": [
"TCGA-XM-A8RL-10A-01D",
"TCGA-XM-A8RL-01A-11R",
"TCGA-XM-A8RL-01A-11D"
],
"analyte_ids": [
"2c483e72-92b0-425d-ac1b-b75a169cf531",
"57f88d4f-8b3a-4349-88b0-3d2e58a95ed9",
"499bfbe1-639c-479c-abaa-42cbb11c0568"
],
"submitter_id": "TCGA-XM-A8RL",
"case_id": "dd240b82-b1d6-4c0f-aa3e-6fcfe1364ec1",
"id": "dd240b82-b1d6-4c0f-aa3e-6fcfe1364ec1",
"disease_type": "Thymoma",
"sample_ids": [
"cb091cc1-7bbe-43a4-8460-01215af3aa21",
"cabc9729-c1e1-4f08-9959-985dcb7a00d5"
],
"portion_ids": [
"e8ea57c9-729e-46ea-b1da-2db7a00b02bc",
"8e2edb92-753f-4cb0-a5b8-8c45dbefaf36",
"650fa4f2-9fa2-4d3a-8b63-ff4a9bd8c33e"
],
"submitter_portion_ids": [
"TCGA-XM-A8RL-01A-21-A45R-20",
"TCGA-XM-A8RL-10A-01",
"TCGA-XM-A8RL-01A-11"
],
"created_datetime": null,
"slide_ids": [
"08cedd34-aafd-4b47-891f-cf66ee1f627b"
],
"state": "live",
"aliquot_ids": [
"df9d8553-8d5b-4c65-8b28-74030a8f8e76",
"47b7f634-b36f-49e9-a4dc-d8f5508fdc0a",
"e692ebed-9721-40db-8986-fcaba07d68f1",
"189ee080-95d1-4ccb-8618-955605c7bd55",
"83af7ff3-45be-4378-a8b5-5dff3584e95d",
"42ebb1f0-e236-48ae-847f-69a153969903",
"e8a4938f-6b93-4ad1-9324-31c97dd1d477"
],
"primary_site": "Thymus",
"submitter_aliquot_ids": [
"TCGA-XM-A8RL-10A-01D-A426-09",
"TCGA-XM-A8RL-01A-11D-A423-09",
"TCGA-XM-A8RL-01A-11D-A422-01",
"TCGA-XM-A8RL-01A-11R-A42C-07",
"TCGA-XM-A8RL-10A-01D-A425-01",
"TCGA-XM-A8RL-01A-11R-A42W-13",
"TCGA-XM-A8RL-01A-11D-A424-05"
],
"submitter_sample_ids": [
"TCGA-XM-A8RL-10A",
"TCGA-XM-A8RL-01A"
],
"submitter_slide_ids": [
"TCGA-XM-A8RL-01A-01-TSA"
]
},
{
"updated_datetime": "2017-03-04T16:39:19.244769-06:00",
"submitter_analyte_ids": [
"TCGA-B0-5120-01A-01W",
"TCGA-B0-5120-01A-01D",
"TCGA-B0-5120-01A-01R",
"TCGA-B0-5120-11A-01W",
"TCGA-B0-5120-11A-01D"
],
"analyte_ids": [
"996336e6-fad7-4100-96ae-60adb5c276f1",
"0eb7da02-0b90-4f6d-abd2-b048a9cb2995",
"fa2861b9-67c1-486a-a1e0-95d8f8adf65b",
"7e9f5639-a462-493e-98f8-1b7aeee383c7",
"d51e9fd4-0c99-49ec-9de5-db3946b0bf43"
],
"submitter_id": "TCGA-B0-5120",
"case_id": "c5bf474c-6919-47b4-ba59-34ab20c087d5",
"id": "c5bf474c-6919-47b4-ba59-34ab20c087d5",
"disease_type": "Kidney Renal Clear Cell Carcinoma",
"sample_ids": [
"b50d3c6f-fdec-488b-ab26-a9b690fad34f",
"f3148210-ecae-4314-b5f8-9bee2315a093"
],
"portion_ids": [
"b8fcbf00-4c5a-42c3-95e9-fb6e169a8da9",
"34443e91-0210-4477-9511-53026ae62b38",
"e466f011-79a1-4158-b796-f8e9dda32d68"
],
"submitter_portion_ids": [
"TCGA-B0-5120-01A-01",
"TCGA-B0-5120-11A-01",
"TCGA-B0-5120-01A-21-1740-20"
],
"created_datetime": null,
"slide_ids": [
"e5a29e92-4125-4acb-a797-86822b4961a2",
"78d873e0-037f-4aef-8725-7c651598b1f8",
"43d8cec7-f5a0-45d5-a5f8-cc77d6b7b539"
],
"state": "live",
"aliquot_ids": [
"b35280fe-dbfa-4e45-8f49-3d0489e68743",
"a2e3a2f2-c32b-44a1-9b29-911145d700b8",
"a064d108-e8b2-46fa-b277-0a7a89904a3a",
"59be71a1-50e3-4565-852a-173afc8a6851",
"136dff0e-b181-49c9-8305-b3289625ea2e",
"8fbb983b-53ad-44a9-976a-7945628eaa51",
"cecf40f8-7301-4db9-b276-a14317d4dd59",
"fac8b066-bf2c-4f08-b42b-251035596a28",
"fa55c92f-54e8-436b-b8c4-04cb68a24e93",
"007e3098-aaf9-4ee7-9ae1-f94b131a5ae0",
"6ce58fbc-6742-4ade-84b0-cd025266e030",
"9668e15e-a3fa-4ead-ad42-322c5700e0db",
"c1167003-0730-41d5-bdd5-1cbf501c1463",
"73aab074-cbd1-45f2-8266-9ef6f7c559bc"
],
"primary_site": "Kidney",
"submitter_aliquot_ids": [
"TCGA-B0-5120-11A-01D-1416-02",
"TCGA-B0-5120-11A-01D-2099-10",
"TCGA-B0-5120-11A-01D-1418-05",
"TCGA-B0-5120-01A-01W-1475-10",
"TCGA-B0-5120-01A-01D-1421-08",
"TCGA-B0-5120-01A-01D-1416-02",
"TCGA-B0-5120-01A-01R-1419-13",
"TCGA-B0-5120-01A-01R-1420-07",
"TCGA-B0-5120-11A-01D-1421-08",
"TCGA-B0-5120-01A-01D-1417-01",
"TCGA-B0-5120-01A-01D-1418-05",
"TCGA-B0-5120-11A-01W-1475-10",
"TCGA-B0-5120-01A-01D-2099-10",
"TCGA-B0-5120-11A-01D-1417-01"
],
"submitter_sample_ids": [
"TCGA-B0-5120-11A",
"TCGA-B0-5120-01A"
],
"submitter_slide_ids": [
"TCGA-B0-5120-11A-01-TS1",
"TCGA-B0-5120-01A-01-BS1",
"TCGA-B0-5120-01A-01-TS1"
]
}
],
"pagination": {
"count": 5,
"sort": "",
"from": 0,
"page": 1,
"total": 14551,
"pages": 2911,
"size": 5
}
},
"warnings": {}
}
This example is a query for cases with a height (follow_ups.other_clinical_attributes.height) equal to or greater than 225, and return the height and project_id the case belongs to. Note: height is expressed in centimeters.
{
"op":">=",
"content":{
"field": "follow_ups.other_clinical_attributes.height",
"value": 225
}
}
curl 'https://api.gdc.cancer.gov/cases?filters=%7B%22op%22%3A%20%22%3E%3D%22%2C%20%22content%22%3A%20%7B%22field%22%3A%20%22follow_ups.other_clinical_attributes.height%22%2C%20%22value%22%3A%20225%7D%7D&fields=follow_ups.other_clinical_attributes.height,project.project_id&pretty=true'
{
"data": {
"hits": [
{
"id": "56a06787-58e9-4cd4-a027-0c0fabcc0983",
"follow_ups": [
{
"other_clinical_attributes": [
{
"height": 243
}
]
}
],
"project": {
"project_id": "MMRF-COMMPASS"
}
}
],
"pagination": {
"count": 1,
"total": 1,
"size": 10,
"from": 0,
"sort": "",
"page": 1,
"pages": 1
}
},
"warnings": {}
}
This example is a query to filter for first 5 cases that have Other Clinical Attribute entities with data and to display the Other Clinical Attribute data and project_id. Note: the not operator filters for fields that are not missing or not empty.
{
"op":"not",
"content":{
"field": "follow_ups.other_clinical_attributes.submitter_id",
}
}
curl 'https://api.gdc.cancer.gov/cases?filters=%7B%22op%22%3A%20%22not%22%2C%20%22content%22%3A%20%7B%22field%22%3A%20%22follow_ups.other_clinical_attributes.submitter_id%22%7D%7D&fields=project.project_id&expand=follow_ups.other_clinical_attributes&size=5&pretty=true'
{
"data": {
"hits": [
{
"id": "4ad1f10e-b45d-4bed-bc99-f3d48254623d",
"follow_ups": [
{
"other_clinical_attributes": [
{
"timepoint_category": "Initial Diagnosis",
"updated_datetime": "2024-07-09T13:45:54.127250-05:00",
"other_clinical_attribute_id": "b1828570-fe96-4b74-8e35-1d7b7c5b25b8",
"weight": 91,
"submitter_id": "CTSP-AD2E_other_clinical_attribute",
"state": "released",
"created_datetime": "2023-11-30T10:08:31.042703-06:00",
"bmi": 39.4,
"height": 152
}
]
}
],
"project": {
"project_id": "CTSP-DLBCL1"
}
},
{
"id": "1cfe090d-9a34-4984-a0d8-392ab83635b3",
"follow_ups": [
{
"other_clinical_attributes": [
{
"timepoint_category": "Initial Diagnosis",
"updated_datetime": "2024-07-09T13:45:54.127250-05:00",
"other_clinical_attribute_id": "c8098f60-394a-422b-a3aa-a3a1c0d9dae7",
"weight": 58,
"submitter_id": "CTSP-AD4C_other_clinical_attribute",
"state": "released",
"created_datetime": "2023-11-30T10:19:30.283698-06:00",
"bmi": 22.4,
"height": 161
}
]
}
],
"project": {
"project_id": "CTSP-DLBCL1"
}
},
{
"id": "297b1cb6-df7d-4e75-a17c-592179be7b71",
"follow_ups": [
{
"other_clinical_attributes": [
{
"timepoint_category": "Initial Diagnosis",
"updated_datetime": "2024-07-09T13:45:54.127250-05:00",
"other_clinical_attribute_id": "069f5ef5-a488-454d-8b28-ca1f81375006",
"weight": 132,
"submitter_id": "CTSP-AD1S_other_clinical_attribute",
"state": "released",
"created_datetime": "2023-11-30T10:01:36.617920-06:00",
"bmi": 45.7,
"height": 170
}
]
}
],
"project": {
"project_id": "CTSP-DLBCL1"
}
},
{
"id": "dd6f8769-ee57-4171-a353-ceb762541845",
"follow_ups": [
{
"other_clinical_attributes": [
{
"timepoint_category": "Initial Diagnosis",
"updated_datetime": "2024-07-09T13:45:54.127250-05:00",
"other_clinical_attribute_id": "5c9c4fe0-aedc-4016-90c6-1075f82a139b",
"weight": 81,
"submitter_id": "CTSP-AD1Z_other_clinical_attribute",
"state": "released",
"created_datetime": "2023-11-30T10:00:47.753276-06:00",
"bmi": 30.1,
"height": 164
}
]
}
],
"project": {
"project_id": "CTSP-DLBCL1"
}
},
{
"id": "19ec7505-20c7-4ba2-bf08-4a8875cb2639",
"follow_ups": [
{
"other_clinical_attributes": [
{
"timepoint_category": "Initial Diagnosis",
"updated_datetime": "2024-07-09T13:45:54.127250-05:00",
"other_clinical_attribute_id": "89938ef7-aa86-49e1-98b6-fd6ee6a4278a",
"weight": 47,
"submitter_id": "CTSP-AD1R_other_clinical_attribute",
"state": "released",
"created_datetime": "2023-11-30T10:01:55.498836-06:00",
"bmi": 20.3,
"height": 152
}
]
}
],
"project": {
"project_id": "CTSP-DLBCL1"
}
}
],
"pagination": {
"count": 5,
"total": 3306,
"size": 5,
"from": 0,
"sort": "",
"page": 1,
"pages": 662
}
},
"warnings": {}
}
Annotations Endpoint Example
This example is a query for annotations contained in the GDC. It returns only the first two annotations.
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": {}
}
Filters Examples
This section contains additional examples for using the filters parameter.
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 Brain.
{
"op": "and",
"content": [
{
"op": "in",
"content": {
"field": "primary_site",
"value": [
"Brain"
]
}
}
]
}
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++++++++++%22Brain%22%0d%0a++++++++%5d%0d%0a++++++%7d%0d%0a++++%7d%0d%0a++%5d%0d%0a%7d&pretty=true'
{
"data": {
"hits": [
{
"id": "HCMI-CMDC",
"primary_site": [
"Stomach",
"Uterus, NOS",
"Connective, subcutaneous and other soft tissues",
"Skin",
"Other and ill-defined sites",
"Brain",
"Bones, joints and articular cartilage of other and unspecified sites",
"Ovary",
"Other and unspecified parts of biliary tract",
"Other and unspecified parts of tongue",
"Corpus uteri",
"Rectosigmoid junction",
"Pancreas",
"Small intestine",
"Gallbladder",
"Kidney",
"Nasal cavity and middle ear",
"Esophagus",
"Liver and intrahepatic bile ducts",
"Other and unspecified parts of mouth",
"Rectum",
"Colon",
"Bronchus and lung",
"Breast"
],
"dbgap_accession_number": null,
"project_id": "HCMI-CMDC",
"disease_type": [
"Soft Tissue Tumors and Sarcomas, NOS",
"Complex Mixed and Stromal Neoplasms",
"Acinar Cell Neoplasms",
"Squamous Cell Neoplasms",
"Osseous and Chondromatous Neoplasms",
"Cystic, Mucinous and Serous Neoplasms",
"Fibromatous Neoplasms",
"Ductal and Lobular Neoplasms",
"Gliomas",
"Epithelial Neoplasms, NOS",
"Blood Vessel Tumors",
"Myomatous Neoplasms",
"Complex Epithelial Neoplasms",
"Adenomas and Adenocarcinomas",
"Nevi and Melanomas",
"Miscellaneous Bone Tumors"
],
"name": "NCI Cancer Model Development for the Human Cancer Model Initiative",
"releasable": true,
"state": "open",
"released": true
},
{
"id": "CPTAC-3",
"primary_site": [
"Bronchus and lung",
"Breast",
"Uterus, NOS",
"Other and ill-defined sites",
"Unknown",
"Kidney",
"Colon",
"Other and unspecified urinary organs",
"Brain",
"Pancreas"
],
"dbgap_accession_number": "phs001287",
"project_id": "CPTAC-3",
"disease_type": [
"Squamous Cell Neoplasms",
"Gliomas",
"Adenomas and Adenocarcinomas",
"Epithelial Neoplasms, NOS",
"Ductal and Lobular Neoplasms",
"Transitional Cell Papillomas and Carcinomas",
"Complex Epithelial Neoplasms",
"Not Applicable",
"Nevi and Melanomas",
"Lipomatous Neoplasms",
"Complex Mixed and Stromal Neoplasms"
],
"name": "CPTAC-Brain, Head and Neck, Kidney, Lung, Pancreas, Uterus",
"releasable": true,
"state": "open",
"released": true
},
{
"id": "MATCH-W",
"primary_site": [
"Prostate gland",
"Rectum",
"Anus and anal canal",
"Bladder",
"Gallbladder",
"Pancreas",
"Breast",
"Other and unspecified female genital organs",
"Thyroid gland",
"Bronchus and lung",
"Cervix uteri",
"Other and unspecified urinary organs",
"Corpus uteri",
"Parotid gland",
"Liver and intrahepatic bile ducts",
"Brain",
"Renal pelvis",
"Other and unspecified major salivary glands"
],
"dbgap_accession_number": "phs001948",
"project_id": "MATCH-W",
"disease_type": [
"Adenomas and Adenocarcinomas",
"Ductal and Lobular Neoplasms",
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Cystic, Mucinous and Serous Neoplasms",
"Squamous Cell Neoplasms",
"Gliomas",
"Transitional Cell Papillomas and Carcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm W",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "MATCH-Z1D",
"primary_site": [
"Small intestine",
"Prostate gland",
"Thyroid gland",
"Other and unspecified female genital organs",
"Bones, joints and articular cartilage of other and unspecified sites",
"Stomach",
"Uterus, NOS",
"Liver and intrahepatic bile ducts",
"Corpus uteri",
"Esophagus",
"Other endocrine glands and related structures",
"Brain",
"Breast",
"Other and unspecified major salivary glands",
"Other and unspecified parts of biliary tract"
],
"dbgap_accession_number": "phs001859",
"project_id": "MATCH-Z1D",
"disease_type": [
"Complex Mixed and Stromal Neoplasms",
"Myomatous Neoplasms",
"Ductal and Lobular Neoplasms",
"Neoplasms, NOS",
"Cystic, Mucinous and Serous Neoplasms",
"Squamous Cell Neoplasms",
"Gliomas",
"Adenomas and Adenocarcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm Z1D",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "MATCH-U",
"primary_site": [
"Ovary",
"Bronchus and lung",
"Connective, subcutaneous and other soft tissues",
"Other and unspecified female genital organs",
"Heart, mediastinum, and pleura",
"Meninges",
"Cervix uteri",
"Liver and intrahepatic bile ducts",
"Brain",
"Kidney",
"Other and unspecified parts of biliary tract"
],
"dbgap_accession_number": "phs002179",
"project_id": "MATCH-U",
"disease_type": [
"Mesothelial Neoplasms",
"Fibromatous Neoplasms",
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Nerve Sheath Tumors",
"Squamous Cell Neoplasms",
"Adenomas and Adenocarcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm U",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "MATCH-H",
"primary_site": [
"Colon",
"Ovary",
"Anus and anal canal",
"Bronchus and lung",
"Pancreas",
"Other and unspecified female genital organs",
"Unknown",
"Bones, joints and articular cartilage of other and unspecified sites",
"Other and ill-defined digestive organs",
"Liver and intrahepatic bile ducts",
"Brain"
],
"dbgap_accession_number": "phs001888",
"project_id": "MATCH-H",
"disease_type": [
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Gliomas",
"Adenomas and Adenocarcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm H",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "MATCH-N",
"primary_site": [
"Small intestine",
"Base of tongue",
"Prostate gland",
"Bronchus and lung",
"Oropharynx",
"Unknown",
"Cervix uteri",
"Corpus uteri",
"Kidney",
"Brain",
"Breast"
],
"dbgap_accession_number": "phs002151",
"project_id": "MATCH-N",
"disease_type": [
"Complex Mixed and Stromal Neoplasms",
"Myomatous Neoplasms",
"Ductal and Lobular Neoplasms",
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Cystic, Mucinous and Serous Neoplasms",
"Squamous Cell Neoplasms",
"Gliomas",
"Adenomas and Adenocarcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm N",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "MATCH-I",
"primary_site": [
"Colon",
"Prostate gland",
"Other and unspecified female genital organs",
"Esophagus",
"Cervix uteri",
"Liver and intrahepatic bile ducts",
"Ovary",
"Anus and anal canal",
"Base of tongue",
"Nasopharynx",
"Brain",
"Kidney",
"Skin",
"Other and unspecified major salivary glands",
"Rectum",
"Bronchus and lung",
"Connective, subcutaneous and other soft tissues",
"Oropharynx",
"Unknown",
"Vagina",
"Corpus uteri",
"Retroperitoneum and peritoneum",
"Other and unspecified parts of mouth",
"Rectosigmoid junction",
"Tonsil",
"Accessory sinuses"
],
"dbgap_accession_number": "phs002181",
"project_id": "MATCH-I",
"disease_type": [
"Soft Tissue Tumors and Sarcomas, NOS",
"Myomatous Neoplasms",
"Nevi and Melanomas",
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Squamous Cell Neoplasms",
"Osseous and Chondromatous Neoplasms",
"Gliomas",
"Adenomas and Adenocarcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm I",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "MATCH-S1",
"primary_site": [
"Colon",
"Ovary",
"Rectum",
"Small intestine",
"Gallbladder",
"Bronchus and lung",
"Connective, subcutaneous and other soft tissues",
"Other and unspecified female genital organs",
"Parotid gland",
"Unknown",
"Stomach",
"Liver and intrahepatic bile ducts",
"Other and ill-defined sites in lip, oral cavity and pharynx",
"Peripheral nerves and autonomic nervous system",
"Corpus uteri",
"Brain",
"Breast",
"Skin"
],
"dbgap_accession_number": "phs002153",
"project_id": "MATCH-S1",
"disease_type": [
"Complex Mixed and Stromal Neoplasms",
"Soft Tissue Tumors and Sarcomas, NOS",
"Myomatous Neoplasms",
"Ductal and Lobular Neoplasms",
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Nerve Sheath Tumors",
"Squamous Cell Neoplasms",
"Gliomas",
"Adenomas and Adenocarcinomas"
],
"name": "Genomic Characterization CS-MATCH-0007 Arm S1",
"releasable": false,
"state": "open",
"released": true
},
{
"id": "EXCEPTIONAL_RESPONDERS-ER",
"primary_site": [
"Colon",
"Other and unspecified female genital organs",
"Esophagus",
"Other and ill-defined digestive organs",
"Ovary",
"Anus and anal canal",
"Pancreas",
"Brain",
"Breast",
"Kidney",
"Skin",
"Rectum",
"Bladder",
"Bronchus and lung",
"Connective, subcutaneous and other soft tissues",
"Unknown",
"Uterus, NOS",
"Stomach",
"Other and unspecified parts of biliary tract",
"Other and ill-defined sites"
],
"dbgap_accession_number": null,
"project_id": "EXCEPTIONAL_RESPONDERS-ER",
"disease_type": [
"Complex Mixed and Stromal Neoplasms",
"Myomatous Neoplasms",
"Ductal and Lobular Neoplasms",
"Nevi and Melanomas",
"Epithelial Neoplasms, NOS",
"Neoplasms, NOS",
"Squamous Cell Neoplasms",
"Gliomas",
"Adenomas and Adenocarcinomas"
],
"name": "Exceptional Responders",
"releasable": false,
"state": "open",
"released": true
}
],
"pagination": {
"count": 10,
"total": 14,
"size": 10,
"from": 0,
"sort": "",
"page": 1,
"pages": 2
}
},
"warnings": {}
}
Example: Filter cases keeping only 'male'
This is an example of a value-based filter:
{
"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'
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.
{
"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'
Example: Multiple fields
Filter projects for primary_site being Kidney or Brain and program.name being TCGA
{
"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%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22program.name%22%2C%22value%22%3A%5B%22TCGA%22%5D%7D%7D%5D%7D&pretty=true'