Skill Tracer
Skills › Scientific Agent Skills › database-lookup › gtex.md

gtex.md

138 lines · skills/database-lookup/references/gtex.md at 5f2bc03

Open on GitHub
1# GTEx (Genotype-Tissue Expression) API Reference
2

GTEx (Genotype-Tissue Expression) API Reference

Raw lines 1 to 2
3## Overview
4GTEx catalogs gene expression levels across human tissues from postmortem donors,
5enabling study of tissue-specific gene regulation and eQTLs.
6

Overview

GTEx catalogs gene expression levels across human tissues from postmortem donors, enabling study of tissue-specific gene regulation and eQTLs.

Raw lines 3 to 6
7## Base URL
8`https://gtexportal.org/api/v2`
9

Base URL

https://gtexportal.org/api/v2

Raw lines 7 to 9
10## Auth
11None required (public, unauthenticated).

Auth

None required (public, unauthenticated).

Raw lines 10 to 12
13## Response Format
14JSON. Most endpoints return paginated results with structure:
15```json
17 "data": [ ... ],
18 "paging_info": {
19 "numberOfPages": 10,
20 "page": 0,
21 "maxItemsPerPage": 250
22 }
24```

Response Format

JSON. Most endpoints return paginated results with structure:

{
  "data": [ ... ],
  "paging_info": {
    "numberOfPages": 10,
    "page": 0,
    "maxItemsPerPage": 250
  }
}
Raw lines 13 to 25
26## Pagination Parameters (common to most endpoints)
27- `page` -- 0-indexed page number (default: 0)
28- `itemsPerPage` -- results per page (default: 250; current schema maximum: 100000, use small pages)

Pagination Parameters (common to most endpoints)

  • page -- 0-indexed page number (default: 0)
  • itemsPerPage -- results per page (default: 250; current schema maximum: 100000, use small pages)
Raw lines 26 to 29
30## Key Endpoints

Key Endpoints

Raw lines 30 to 31
32### Gene expression (median by tissue)
33```
34GET /expression/medianGeneExpression?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
35```
36Parameters:
37- `gencodeId` -- Versioned Ensembl gene ID (required)
38- `datasetId` -- `gtex_v8` (explicit historical selection; defaults vary by endpoint)
39- `tissueSiteDetailId` -- filter to specific tissue (optional)
41Returns median TPM per tissue for the gene.

Gene expression (median by tissue)

GET /expression/medianGeneExpression?gencodeId=ENSG00000139618.14&datasetId=gtex_v8

Parameters:

  • gencodeId -- Versioned Ensembl gene ID (required)
  • datasetId -- gtex_v8 (explicit historical selection; defaults vary by endpoint)
  • tissueSiteDetailId -- filter to specific tissue (optional)

Returns median TPM per tissue for the gene.

Raw lines 32 to 42
43### Highly expressed genes for a tissue
44```
45GET /expression/topExpressedGene?tissueSiteDetailId=Liver&datasetId=gtex_v8
46```

Highly expressed genes for a tissue

GET /expression/topExpressedGene?tissueSiteDetailId=Liver&datasetId=gtex_v8
Raw lines 43 to 47
48### Single-tissue eQTLs
49```
50GET /association/singleTissueEqtl?gencodeId=ENSG00000139618.14&tissueSiteDetailId=Whole_Blood&datasetId=gtex_v8
51```
52Parameters:
53- `gencodeId` -- Versioned Ensembl gene ID (optional filter)
54- `tissueSiteDetailId` -- tissue ID (optional filter)
55- `datasetId` -- `gtex_v8` (explicit historical selection; defaults vary by endpoint)

Single-tissue eQTLs

GET /association/singleTissueEqtl?gencodeId=ENSG00000139618.14&tissueSiteDetailId=Whole_Blood&datasetId=gtex_v8

Parameters:

  • gencodeId -- Versioned Ensembl gene ID (optional filter)
  • tissueSiteDetailId -- tissue ID (optional filter)
  • datasetId -- gtex_v8 (explicit historical selection; defaults vary by endpoint)
Raw lines 48 to 56
57### Multi-tissue eQTLs
58```
59GET /association/metasoft?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
60```

Multi-tissue eQTLs

GET /association/metasoft?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
Raw lines 57 to 61
62### Gene search
63```
64GET /reference/gene?geneId=BRCA2&gencodeVersion=v26&genomeBuild=GRCh38/hg38
65```
66Parameters:
67- `geneId` -- gene symbol or Ensembl ID
68- `gencodeVersion` -- `v26` for GTEx v8
69- `genomeBuild` -- `GRCh38/hg38`

Gene search

GET /reference/gene?geneId=BRCA2&gencodeVersion=v26&genomeBuild=GRCh38/hg38

Parameters:

  • geneId -- gene symbol or Ensembl ID
  • gencodeVersion -- v26 for GTEx v8
  • genomeBuild -- GRCh38/hg38
Raw lines 62 to 70
71### List tissues
72```
73GET /dataset/tissueSiteDetail?datasetId=gtex_v8
74```
75Returns all tissue site detail IDs, names, colors, sample counts.

List tissues

GET /dataset/tissueSiteDetail?datasetId=gtex_v8

Returns all tissue site detail IDs, names, colors, sample counts.

Raw lines 71 to 76
77### Exon expression
78```
79GET /expression/medianExonExpression?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
80```

Exon expression

GET /expression/medianExonExpression?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
Raw lines 77 to 81
82### Transcript expression
83```
84GET /expression/medianTranscriptExpression?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
85```

Transcript expression

GET /expression/medianTranscriptExpression?gencodeId=ENSG00000139618.14&datasetId=gtex_v8
Raw lines 82 to 86
87### Top expressed genes in a tissue
88```
89GET /expression/topExpressedGene?tissueSiteDetailId=Brain_Cortex&datasetId=gtex_v8&filterMtGene=true
90```

Top expressed genes in a tissue

GET /expression/topExpressedGene?tissueSiteDetailId=Brain_Cortex&datasetId=gtex_v8&filterMtGene=true
Raw lines 87 to 91
92### Dynamic eQTL query for a gene–variant–tissue combination
93```
94GET /association/dyneqtl?variantId=chr1_1000000_A_G_b38&gencodeId=ENSG00000139618.14&tissueSiteDetailId=Whole_Blood&datasetId=gtex_v8
95```

Dynamic eQTL query for a gene–variant–tissue combination

GET /association/dyneqtl?variantId=chr1_1000000_A_G_b38&gencodeId=ENSG00000139618.14&tissueSiteDetailId=Whole_Blood&datasetId=gtex_v8
Raw lines 92 to 96
97## Tissue ID examples
98Use the underscore-separated names exactly:
99- `Whole_Blood`, `Liver`, `Brain_Cortex`, `Heart_Left_Ventricle`
100- `Muscle_Skeletal`, `Adipose_Subcutaneous`, `Lung`, `Skin_Sun_Exposed_Lower_leg`

Tissue ID examples

Use the underscore-separated names exactly:

  • Whole_Blood, Liver, Brain_Cortex, Heart_Left_Ventricle
  • Muscle_Skeletal, Adipose_Subcutaneous, Lung, Skin_Sun_Exposed_Lower_leg
Raw lines 97 to 101
102## Example response (median gene expression)
103```json
105 "data": [
106 {
107 "datasetId": "gtex_v8",
108 "gencodeId": "ENSG00000139618.14",
109 "geneSymbol": "BRCA2",
110 "median": 4.523,
111 "tissueSiteDetailId": "Whole_Blood",
112 "unit": "TPM"
113 },
114 {
115 "datasetId": "gtex_v8",
116 "gencodeId": "ENSG00000139618.14",
117 "geneSymbol": "BRCA2",
118 "median": 12.87,
119 "tissueSiteDetailId": "Testis",
120 "unit": "TPM"
121 }
122 ],
123 "paging_info": { "numberOfPages": 1, "page": 0, "maxItemsPerPage": 250 }
125```

Example response (median gene expression)

{
  "data": [
    {
      "datasetId": "gtex_v8",
      "gencodeId": "ENSG00000139618.14",
      "geneSymbol": "BRCA2",
      "median": 4.523,
      "tissueSiteDetailId": "Whole_Blood",
      "unit": "TPM"
    },
    {
      "datasetId": "gtex_v8",
      "gencodeId": "ENSG00000139618.14",
      "geneSymbol": "BRCA2",
      "median": 12.87,
      "tissueSiteDetailId": "Testis",
      "unit": "TPM"
    }
  ],
  "paging_info": { "numberOfPages": 1, "page": 0, "maxItemsPerPage": 250 }
}
Raw lines 102 to 126
127## Rate Limits
128- No published rate limits
129- Reasonable request pacing recommended (~1-2 req/sec)
130- For bulk analysis, download full datasets from the GTEx Portal downloads page

Rate Limits

  • No published rate limits
  • Reasonable request pacing recommended (~1-2 req/sec)
  • For bulk analysis, download full datasets from the GTEx Portal downloads page
Raw lines 127 to 131
132## Notes
133- These examples intentionally pin the historical GTEx v8 dataset. Current expression and single-tissue eQTL endpoints default to `gtex_v10`, while metasoft/dyneqtl default to v8. Specify the dataset and resolve gene IDs using its compatible GENCODE release; do not mix gene versions across datasets.
134- Gene IDs must be versioned GENCODE IDs (e.g., ENSG00000139618.14)
135- Use the gene search endpoint to resolve symbols to versioned GENCODE IDs
136- `gencodeVersion=v26` corresponds to GTEx v8
138Official schema: https://gtexportal.org/api/v2/openapi.json

Notes

  • These examples intentionally pin the historical GTEx v8 dataset. Current expression and single-tissue eQTL endpoints default to gtex_v10, while metasoft/dyneqtl default to v8. Specify the dataset and resolve gene IDs using its compatible GENCODE release; do not mix gene versions across datasets.
  • Gene IDs must be versioned GENCODE IDs (e.g., ENSG00000139618.14)
  • Use the gene search endpoint to resolve symbols to versioned GENCODE IDs
  • gencodeVersion=v26 corresponds to GTEx v8

Official schema: https://gtexportal.org/api/v2/openapi.json

Raw lines 132 to 138