Skill Tracer
Skills › Scientific Agent Skills › database-lookup › tcga-gdc.md

tcga-gdc.md

58 lines · skills/database-lookup/references/tcga-gdc.md at 5f2bc03

Open on GitHub
1# TCGA / GDC Data Portal API
2

TCGA / GDC Data Portal API

Raw lines 1 to 2
3## Base URL
4```
5https://api.gdc.cancer.gov
6```
7

Base URL

https://api.gdc.cancer.gov
Raw lines 3 to 7
8## Auth
9No auth for public data. Token needed only for controlled-access downloads.

Auth

No auth for public data. Token needed only for controlled-access downloads.

Raw lines 8 to 10
11## Key Endpoints
13All search endpoints accept GET or POST (POST preferred for complex filters).
15| Endpoint | Description |
16|----------|-------------|
17| `/projects` | List/filter cancer projects (e.g. TCGA-BRCA) |
18| `/cases` | Search cases (patients/samples) |
19| `/files` | Search/filter files (BAM, VCF, expression) |
20| `/genes` | Search gene-level data |
21| `/ssms` | Search simple somatic mutations |
22| `/ssm_occurrences` | Mutation occurrences across cases |
23| `/files/{uuid}` | File metadata by UUID |
24| `/data/{uuid}` | Download file by UUID |

Key Endpoints

All search endpoints accept GET or POST (POST preferred for complex filters).

EndpointDescription
/projectsList/filter cancer projects (e.g. TCGA-BRCA)
/casesSearch cases (patients/samples)
/filesSearch/filter files (BAM, VCF, expression)
/genesSearch gene-level data
/ssmsSearch simple somatic mutations
/ssm_occurrencesMutation occurrences across cases
/files/{uuid}File metadata by UUID
/data/{uuid}Download file by UUID
Raw lines 11 to 25
26## Filter Syntax (POST body)
27```json
29 "filters": {
30 "op": "in",
31 "content": {"field": "cases.project.project_id", "value": ["TCGA-BRCA"]}
32 },
33 "fields": "file_id,file_name,data_type",
34 "format": "JSON",
35 "size": 10
37```
38Operators: `in`, `=`, `!=`, `>`, `<`, `>=`, `<=`, `is`, `not`, `and`, `or`

Filter Syntax (POST body)

{
  "filters": {
    "op": "in",
    "content": {"field": "cases.project.project_id", "value": ["TCGA-BRCA"]}
  },
  "fields": "file_id,file_name,data_type",
  "format": "JSON",
  "size": 10
}

Operators: in, =, !=, >, <, >=, <=, is, not, and, or

Raw lines 26 to 39
40## Example Calls
41```
42# List projects
43https://api.gdc.cancer.gov/projects?size=5&fields=project_id,name,primary_site
45# BRCA1 mutations (POST)
46curl -X POST https://api.gdc.cancer.gov/ssms \
47 -H "Content-Type: application/json" \
48 -d '{"filters":{"op":"in","content":{"field":"consequence.transcript.gene.symbol","value":["BRCA1"]}},"fields":"ssm_id,genomic_dna_change","size":5}'
50# Cases in TCGA-LUAD
51https://api.gdc.cancer.gov/cases?filters=%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22project.project_id%22%2C%22value%22%3A%5B%22TCGA-LUAD%22%5D%7D%7D&size=3&fields=submitter_id,disease_type
52```

Example Calls

# List projects
https://api.gdc.cancer.gov/projects?size=5&fields=project_id,name,primary_site

# BRCA1 mutations (POST)
curl -X POST https://api.gdc.cancer.gov/ssms \
  -H "Content-Type: application/json" \
  -d '{"filters":{"op":"in","content":{"field":"consequence.transcript.gene.symbol","value":["BRCA1"]}},"fields":"ssm_id,genomic_dna_change","size":5}'

# Cases in TCGA-LUAD
https://api.gdc.cancer.gov/cases?filters=%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22project.project_id%22%2C%22value%22%3A%5B%22TCGA-LUAD%22%5D%7D%7D&size=3&fields=submitter_id,disease_type
Raw lines 40 to 53
54## Pagination
55`from` (offset) and `size` (limit, max 10000). Default size is 10.

Pagination

from (offset) and size (limit, max 10000). Default size is 10.

Raw lines 54 to 56
57## Rate Limits
58No fixed metadata rate guarantee is assumed. Honor throttling, inspect `data.pagination`, and use the GDC Data Transfer Tool for large downloads. Controlled-access authorization is file-specific; a successful public metadata search does not authorize its files.

Rate Limits

No fixed metadata rate guarantee is assumed. Honor throttling, inspect data.pagination, and use the GDC Data Transfer Tool for large downloads. Controlled-access authorization is file-specific; a successful public metadata search does not authorize its files.

Raw lines 57 to 58