Look up genes, sequences, variants, homologs, and cross-database xrefs from Ensembl REST.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Find orthologs and/or paralogs of a gene across species. Returns each homolog's stable ID, species, homology type (ortholog_one2one, ortholog_one2many, paralog_many2many, etc.), percId (percent identity), percPos (percent positives), and taxonomy level. Essential for cross-species research — for example, "what is the mouse equivalent of human TP53?" or "how conserved is BRCA2 across mammals?". Provide either symbol + species or a stable gene ID. Target species can be filtered to a single species or left open to return all available homologs. Includes targetProteinId when available for ensembl_get_sequence with type="protein". targetSymbol is best-effort: a secondary gene lookup shares five seconds across the returned rows and the remaining call deadline; missing names never remove homologs.
Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix (ENSG00000139618.17) is accepted and dropped before the query. Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol.
Type of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs.
Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id.
Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values.
Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap.
Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species with nameContains (a genus or common name) to find valid values.
Find orthologs and/or paralogs of a gene across species. Returns each homolog's stable ID, species, homology type (ortholog_one2one, ortholog_one2many, paralog_many2many, etc.), percId (percent identity), percPos (percent positives), and taxonomy level. Essential for cross-species research — for example, "what is the mouse equivalent of human TP53?" or "how conserved is BRCA2 across mammals?". Provide either symbol + species or a stable gene ID. Target species can be filtered to a single species or left open to return all available homologs. Includes targetProteinId when available for ensembl_get_sequence with type="protein". targetSymbol is best-effort: a secondary gene lookup shares five seconds across the returned rows and the remaining call deadline; missing names never remove homologs.
| Argument | Type | Description |
|---|---|---|
| id | string | Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix (ENSG00000139618.17) is accepted and dropped before the query. Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol. |
| type | string | Type of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs. |
| symbol | string | Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id. |
| species | string | Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values. |
| max_results | integer | Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap. |
| target_species | string | Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species with nameContains (a genus or common name) to find valid values. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
"type": "string",
"description": "Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix (ENSG00000139618.17) is accepted and dropped before the query. Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol."
},
"type": {
"enum": [
"orthologues",
"paralogues",
"all"
],
"type": "string",
"default": "orthologues",
"description": "Type of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs."
},
"symbol": {
"type": "string",
"description": "Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id."
},
"species": {
"type": "string",
"default": "homo_sapiens",
"minLength": 1,
"description": "Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values."
},
"max_results": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap."
},
"target_species": {
"type": "string",
"description": "Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species with nameContains (a genus or common name) to find valid values."
}
},
"additionalProperties": false
}Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region. Returns a window of the sequence — the first 10,000 characters by default — with its stable ID, molecule type, and full length. When more follows the window, truncated is true and nextOffset is the offset to request next; walking nextOffset reconstructs the whole sequence, and max_length 0 returns everything from offset to the end. The type parameter selects which sequence is fetched: genomic (default, includes introns), cdna (spliced transcript), cds (coding sequence only), protein. For region mode, set id to a region — either species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end with species set (e.g. id 13:32315086-32400268, species homo_sapiens), spanning at most 10,000,000 bases; a :-1 suffix (13:32315086-32315100:-1) returns the reverse-strand sequence. Regions return genomic DNA only. Protein sequences require a transcript or protein stable ID (ENST…/ENSP…), not a gene ID — use ensembl_lookup_gene and its canonicalTranscript field first; expand_transcripts=true also supplies transcript biotypes and MANE Select accessions.
| Argument | Type | Description |
|---|---|---|
| id* | string | Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode — an id containing a colon is a region. A version suffix on a stable ID (ENST00000380152.8) is dropped before the request. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. Coordinates are whole numbers; start..end works as well as start-end, and a :1 or :-1 suffix picks the strand (13:32315086-32315100:-1 returns the reverse complement). A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases. Name chromosomes as Ensembl does (13, X, MT; chr13 also works); 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); elsewhere they fail as invalid_region naming the mitochondrion of the species. |
Retrieve cross-database references for a gene or feature — HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome, and others. Returns each xref with its database name, primary ID, display ID, and description. By default only the requested object level is queried; all_levels=true includes transcript and translation references for a gene. The dbname filter narrows this scope. IDs returned here chain to protein (pubchem via UniProt), literature (pubmed via PubMed IDs), disease (OMIM via MIM_GENE), and pathway (Reactome) resources. Requires an Ensembl stable ID — use ensembl_lookup_gene to get the ENSG… ID first. Common dbname values: HGNC, Uniprot_gn, EntrezGene, MIM_GENE, RefSeq_mRNA, RefSeq_peptide, Reactome_gene (gene pathways), Reactome (translation pathways), GO (Gene Ontology), ChEMBL.
| Argument | Type | Description |
|---|---|---|
| id* | string | Ensembl stable gene (ENSG…), transcript (ENST…), or translation (ENSP…) ID. A version suffix on an ENS… ID (ENSG00000139618.17) is dropped before the request. Use ensembl_lookup_gene to get the stable ID from a gene symbol. References default to this object level; all_levels=true includes child objects. |
| dbname | string | Filter to a specific external database by its Ensembl internal name. Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), RefSeq_mRNA (NCBI RefSeq transcript), Reactome_gene (gene pathways), Reactome (translation pathways), GO (Gene Ontology terms). Transcript/translation references may require all_levels=true or the specific feature ID. Omit to return every database within the selected scope. |
| all_levels | boolean | Include references on child objects: a gene includes its transcripts and translations. Default false queries only the requested object level, independently of dbname. |
List species supported by Ensembl with display name, common name, assembly, taxon ID, and division. Required discovery step — species names like homo_sapiens are opaque to non-biologists and are the input format every other Ensembl tool expects. Use nameContains to find a species by partial name match; filter by division to select one. With no division, lists the endpoint default division — the vertebrates (~356 species on the default GRCh38 endpoint). Species are sorted by internal name and returned max_results at a time (default 50); totalCount reports every match, and when more follow, nextOffset is the offset for the next page.
| Argument | Type | Description |
|---|---|---|
| offset | integer | 0-based position in the name-sorted matches 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 species. |
| division | string | Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates). |
| max_results | integer | Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap. |
| nameContains | string | Case-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: "sapiens" matches homo_sapiens; "mouse" matches mus_musculus. |
Resolve a gene by symbol + species (or by stable ID) to its Ensembl ID, genomic location (chr:start-end:strand), biotype, description, and transcript list. Entry point for most workflows — the stable ID and coordinates returned here are inputs to other tools. Accepts both symbol lookup (BRCA2 + homo_sapiens) and direct ID lookup (ENSG00000139618). A symbol that is not a current gene name is matched against synonyms and former symbols (HER2 → ERBB2), reported as matchedAlias; when it maps to several genes the result is ambiguous, listing the candidates to retry by id. Supports batch submission of up to 1,000 IDs or symbols: the first 20 distinct queries are resolved, and batch.omitted names the unattempted remainder to resubmit. Provide exactly one of symbol, id, ids, or symbols. For symbol lookups species defaults to homo_sapiens (override for other organisms); for ID lookups species is not needed. Use ensembl_list_species with nameContains (a genus or common name) to find valid species names.
| Argument | Type | Description |
|---|---|---|
| id | string | Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix on an ENS… ID (ENSG00000139618.19) is dropped before the lookup, which returns the current version. Species is not required for ID lookup. |
| ids | array | Batch submission: up to 1,000 Ensembl stable IDs (ENSG…, ENST…); resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed/omitted partition; each attempted item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols. |
| symbol | string | Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species. A synonym or former symbol (HER2, TB1) resolves too; one shared by several genes returns ambiguous with the candidates instead of gene. |
Predict the functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP). Accepts three input formats: HGVS notation (transcript-relative, e.g. ENST00000380152.8:c.2T>A, or genomic, e.g. 13:g.32316462T>A); region+allele (chr:start:end:strand/allele, e.g. 1:65568:65568:1/T); and a dbSNP rsID (e.g. rs334). Returns the most severe consequence term, affected transcripts and genes, impact level (HIGH/MODERATE/LOW/MODIFIER), and any colocated known variants with clinical significance. HGVS input: provide the full notation including transcript version for best results. Region+allele input: Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (a chr-prefixed name is also accepted). By default the response caps transcript consequences (max_transcript_consequences) and per-variant PubMed IDs (max_pubmed_ids_per_variant) to keep large VEP results compact — well-studied variants like rs334 otherwise carry 60+ consequences and 100+ citations. Truthful totals are always reported; set a cap to 0 (or include_all_colocated_pubmed=true) to retrieve the full set.
| Argument | Type | Description |
|---|---|---|
| species | string | Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species with nameContains (a genus or common name) to find valid values. |
| variant* | string | Variant in one of three formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T (strand is 1 for forward or -1 for reverse); (3) dbSNP rsID — e.g. rs334. Ensembl normalizes chromosome names; canonical vertebrate output omits the "chr" prefix, though a chr-prefixed name is also accepted. |
Find 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. The response returns up to max_results features (default 100) while totalCount always reports the full count; set max_results to 0 for every feature, or query a smaller region to see a different slice. Exon rows carry the parent transcript ID, so the same exon appears once per transcript it belongs to.
| Argument | Type | Description |
|---|---|---|
| region* | string | 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. |
| type | string | Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID. A protein ID (ENSP…) serves only its protein; a non-coding transcript has no protein or cds. |
| offset | integer | 0-based character offset where the returned window starts, counted in the resolved sequence (including any expand_5prime/expand_3prime flank). Default 0. Pass nextOffset from a truncated response to fetch the following window; an offset at or past the end returns an empty window. |
| species | string | Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region. For the species:chr:start-end form the species in id takes precedence and this field is ignored. Unused for stable ID lookups — Ensembl infers species from the ID prefix. |
| max_length | integer | Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped. |
| expand_3prime | integer | Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the lower coordinate. |
| expand_5prime | integer | Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the higher coordinate. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode — an id containing a colon is a region. A version suffix on a stable ID (ENST00000380152.8) is dropped before the request. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. Coordinates are whole numbers; start..end works as well as start-end, and a :1 or :-1 suffix picks the strand (13:32315086-32315100:-1 returns the reverse complement). A region needs start at or below end, within the sequence region, and spans at most 10,000,000 bases. Name chromosomes as Ensembl does (13, X, MT; chr13 also works); 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); elsewhere they fail as invalid_region naming the mitochondrion of the species."
},
"type": {
"enum": [
"genomic",
"cdna",
"cds",
"protein"
],
"type": "string",
"default": "genomic",
"description": "Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). Region ids are genomic-only — request cdna, cds, or protein from a transcript or protein stable ID. A protein ID (ENSP…) serves only its protein; a non-coding transcript has no protein or cds."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "0-based character offset where the returned window starts, counted in the resolved sequence (including any expand_5prime/expand_3prime flank). Default 0. Pass nextOffset from a truncated response to fetch the following window; an offset at or past the end returns an empty window."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region. For the species:chr:start-end form the species in id takes precedence and this field is ignored. Unused for stable ID lookups — Ensembl infers species from the ID prefix."
},
"max_length": {
"type": "integer",
"default": 10000,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of characters in the returned window. Default 10000. Set to 0 to return everything from offset to the end, uncapped."
},
"expand_3prime": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the lower coordinate."
},
"expand_5prime": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries; on a :-1 region it extends the higher coordinate."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Ensembl stable gene (ENSG…), transcript (ENST…), or translation (ENSP…) ID. A version suffix on an ENS… ID (ENSG00000139618.17) is dropped before the request. Use ensembl_lookup_gene to get the stable ID from a gene symbol. References default to this object level; all_levels=true includes child objects."
},
"dbname": {
"type": "string",
"description": "Filter to a specific external database by its Ensembl internal name. Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), RefSeq_mRNA (NCBI RefSeq transcript), Reactome_gene (gene pathways), Reactome (translation pathways), GO (Gene Ontology terms). Transcript/translation references may require all_levels=true or the specific feature ID. Omit to return every database within the selected scope."
},
"all_levels": {
"type": "boolean",
"default": false,
"description": "Include references on child objects: a gene includes its transcripts and translations. Default false queries only the requested object level, independently of dbname."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "0-based position in the name-sorted matches 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 species."
},
"division": {
"enum": [
"EnsemblVertebrates",
"EnsemblPlants",
"EnsemblFungi",
"EnsemblMetazoa",
"EnsemblProtists"
],
"type": "string",
"description": "Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates)."
},
"max_results": {
"type": "integer",
"default": 50,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap."
},
"nameContains": {
"type": "string",
"description": "Case-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: \"sapiens\" matches homo_sapiens; \"mouse\" matches mus_musculus."
}
},
"additionalProperties": false
}| species | string | Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species with nameContains (a genus or common name) to find valid values. |
| symbols | array | Batch submission: up to 1,000 gene symbols; resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed/omitted partition; each attempted item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols. |
| expand_transcripts | boolean | When true, include the full transcript list in the response. Each transcript has its ID, biotype, canonical flag, and coordinates. Default is false to keep responses compact. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
"type": "string",
"description": "Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix on an ENS… ID (ENSG00000139618.19) is dropped before the lookup, which returns the current version. Species is not required for ID lookup."
},
"ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "An Ensembl stable gene or transcript ID to resolve in this batch."
},
"maxItems": 1000,
"description": "Batch submission: up to 1,000 Ensembl stable IDs (ENSG…, ENST…); resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed/omitted partition; each attempted item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols."
},
"symbol": {
"type": "string",
"description": "Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species. A synonym or former symbol (HER2, TB1) resolves too; one shared by several genes returns ambiguous with the candidates instead of gene."
},
"species": {
"type": "string",
"description": "Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species with nameContains (a genus or common name) to find valid values."
},
"symbols": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "A gene symbol to resolve in this batch (e.g. BRCA2, TP53)."
},
"maxItems": 1000,
"description": "Batch submission: up to 1,000 gene symbols; resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed/omitted partition; each attempted item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols."
},
"expand_transcripts": {
"type": "boolean",
"default": false,
"description": "When true, include the full transcript list in the response. Each transcript has its ID, biotype, canonical flag, and coordinates. Default is false to keep responses compact."
}
},
"additionalProperties": false
}| max_pubmed_ids_per_variant |
| integer |
| Maximum PubMed IDs to return per colocated known variant. Well-studied variants (e.g. rs334) cite 100+ papers; the default trims each list. Set to 0 to return every PubMed ID uncapped. pubmedTotal on each colocated variant reports the true pre-cap count. Ignored when include_all_colocated_pubmed is true. |
| max_transcript_consequences | integer | Maximum transcript consequences to return per VEP record. High-impact variants can affect 60+ transcripts; the default keeps the response focused on the top consequences. Set to 0 to return every transcript consequence uncapped. transcriptConsequencesTotal on each record always reports the true pre-cap count. |
| include_all_colocated_pubmed | boolean | When true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"variant"
],
"properties": {
"species": {
"type": "string",
"default": "homo_sapiens",
"minLength": 1,
"description": "Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species with nameContains (a genus or common name) to find valid values."
},
"variant": {
"type": "string",
"minLength": 1,
"description": "Variant in one of three formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T (strand is 1 for forward or -1 for reverse); (3) dbSNP rsID — e.g. rs334. Ensembl normalizes chromosome names; canonical vertebrate output omits the \"chr\" prefix, though a chr-prefixed name is also accepted."
},
"max_pubmed_ids_per_variant": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum PubMed IDs to return per colocated known variant. Well-studied variants (e.g. rs334) cite 100+ papers; the default trims each list. Set to 0 to return every PubMed ID uncapped. pubmedTotal on each colocated variant reports the true pre-cap count. Ignored when include_all_colocated_pubmed is true."
},
"max_transcript_consequences": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum transcript consequences to return per VEP record. High-impact variants can affect 60+ transcripts; the default keeps the response focused on the top consequences. Set to 0 to return every transcript consequence uncapped. transcriptConsequencesTotal on each record always reports the true pre-cap count."
},
"include_all_colocated_pubmed": {
"type": "boolean",
"default": false,
"description": "When true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact."
}
},
"additionalProperties": false
}| biotype |
| string |
| Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Case-sensitive (lncRNA, not lncrna); remove the filter to inspect all matching feature types. Applied server-side by Ensembl. Not all feature types support biotype filtering. |
| feature | array | 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 | string | 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 | integer | Maximum number of features to return. A gene-length region can hold tens of thousands of variation features; the default keeps the response compact. Set to 0 to return every feature uncapped. totalCount always reports the true number found before this cap. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"region"
],
"properties": {
"region": {
"type": "string",
"minLength": 1,
"description": "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": {
"type": "string",
"description": "Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Case-sensitive (lncRNA, not lncrna); remove the filter to inspect all matching feature types. Applied server-side by Ensembl. Not all feature types support biotype filtering."
},
"feature": {
"type": "array",
"items": {
"enum": [
"gene",
"transcript",
"variation",
"regulatory",
"exon"
],
"type": "string",
"description": "A feature type to retrieve: gene, transcript, variation, regulatory, or exon."
},
"default": [
"gene"
],
"minItems": 1,
"description": "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": {
"type": "string",
"minLength": 1,
"description": "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": {
"type": "integer",
"default": 100,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of features to return. A gene-length region can hold tens of thousands of variation features; the default keeps the response compact. Set to 0 to return every feature uncapped. totalCount always reports the true number found before this cap."
}
},
"additionalProperties": false
}