Query Genomic Region
ensembl_query_regionFind genomic features overlapping a chromosomal region: genes, transcripts, variants, regulatory elements, or exons. Returns each feature with its stable ID, type, location, biotype, and name, plus the genome assembly the coordinates are on. Useful for "what's in this locus?" and for seeding follow-up lookups. Region format is chr:start-end with species set (e.g. 13:32315086-32400268 for the BRCA2 locus), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), spanning at most 5,000,000 bases. Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. The feature parameter defaults to gene only — requesting variation in an 85 kb region matches 44,000+ entries. Explicitly include variation, regulatory, transcript, or exon only when needed. Features come in one fixed order — by requested feature type, then start, end, ID, and parent transcript — max_results at a time (default 25); totalCount reports every match, and when more follow, nextOffset is the offset for the next page. Exon rows carry the parent transcript ID, so the same exon appears once per transcript it belongs to.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"region": "<region>"
},
"name": "ensembl_query_region"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | 0-based position in the ordered features where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no features. | |
| region | Yes | Genomic region as chr:start-end with species set (e.g. 13:32315086-32400268), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), with start at or below end. Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. The mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans; M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one) and otherwise fail as invalid_region naming the mitochondrion of the species. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results. | |
| biotype | No | Optional biotype filter (e.g. protein_coding, lncRNA), applied by Ensembl to gene, transcript, and exon features — an exon by its parent transcript's biotype. Variation and regulatory features carry no biotype and come back unfiltered. Case-sensitive (lncRNA, not lncrna); remove the filter to inspect every matching feature. | |
| feature | No | Feature types to retrieve — at least one. Default is gene only. Requesting variation in a large region can match tens of thousands of features. Include variation only for targeted small regions (single gene loci or smaller). | |
| species | No | Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Required for a bare chr:start-end region; for the species:chr:start-end form the species in region takes precedence and this field is ignored. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values. | |
| max_results | No | Number of features to return, counted from offset. Default 25; 0 returns 5,000 and says so. A value above 5,000 is clamped to 5,000 with a notice, or rejected where the server is set to reject it. totalCount always reports the full number found. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The max_results value applied to this page, after any clamp to 5,000. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of features returned on this page. | |
| notice | No | Guidance about the result set: empty, offset past the end, max_results clamped, more features following, biotype not applied to a requested type, large, or missing assembly. | |
| region | No | The region queried, as provided minus any species prefix (reported as species). | |
| species | No | The species queried: the region's species prefix when it has one, otherwise the species field. | |
| features | No | One page of the features overlapping the region: at most max_results, starting at offset, ordered by requested feature type, then start, end, ID, and parent transcript. | |
| truncated | No | True when more features follow this page; pass nextOffset as offset to continue. | |
| nextOffset | No | Offset of the first feature after this page — pass it as offset to fetch the next page. Present only when more features follow. | |
| totalCount | No | Total number of features overlapping the region, before offset and max_results. Exceeds the returned features count when the list was paged. | |
| assemblyName | No | Genome assembly the coordinates are on (e.g. GRCh38). Omitted only when it could not be resolved, in which case the notice says so. |