[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ECZXNRRXB96HKBBKVM5BZP":3,"skill-same:01M7ECZXNRRXB96HKBBKVM5BZP":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":14,"repositoryHtmlUrl":33,"repositoryHomepageUrl":33,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":35,"install":36,"resources":49},"01M7ECZXNRRXB96HKBBKVM5BZP","bio-ensembl-rest",null,"Query the Ensembl REST API for gene\u002Ftranscript\u002Fprotein lookup, sequence retrieval, comparative genomics (Compara), variant effect prediction (VEP), regulatory features, and cross-species ortholog\u002Fparalog calls. Use when pulling Ensembl-native data (Ensembl Gene IDs, version-pinned releases, archive endpoints for reproducibility), gene\u002Ftranscript\u002Fexon structure with stable IDs, or VEP for variant annotation. Encodes the 15 req\u002Fsec rate limit, archive (e110.rest.ensembl.org) for reproducibility, Ensembl divisions (vertebrates \u002F plants \u002F fungi \u002F metazoa \u002F bacteria), and the symbol-vs-ID stability problem.","Mr-Nobody-Anonymous\u002FAll-skills","Mr-Nobody-Anonymous","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F184253119?v=4","01M7AEXFJHKTYQW5R0ZCQQTWFV","anonymous","01M7C00M3GQR4QKP9GZA42GFAK",0,"MIT","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-ensembl-rest\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-ensembl-rest\ndescription: Query the Ensembl REST API for gene\u002Ftranscript\u002Fprotein lookup, sequence retrieval, comparative genomics (Compara), variant effect prediction (VEP), regulatory features, and cross-species ortholog\u002Fparalog calls. Use when pulling Ensembl-native data (Ensembl Gene IDs, version-pinned releases, archive endpoints for reproducibility), gene\u002Ftranscript\u002Fexon structure with stable IDs, or VEP for variant annotation. Encodes the 15 req\u002Fsec rate limit, archive (e110.rest.ensembl.org) for reproducibility, Ensembl divisions (vertebrates \u002F plants \u002F fungi \u002F metazoa \u002F bacteria), and the symbol-vs-ID stability problem.\ntool_type: python\nprimary_tool: requests\nsource: \"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills\"\nsource_repository: \"GPTomics\u002FbioSkills\"\nsource_path: \"database-access\u002Fensembl-rest\u002FSKILL.md\"\nlicense: \"MIT\"\nimported_at: \"2026-09-20\"\n---\n\n## Version Compatibility\n\nReference examples tested with: requests 2.31+, Ensembl REST API (release 110+); Ensembl release schedule is roughly quarterly\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- Python: `pip show requests`\n- API surface: check release notes at https:\u002F\u002Frest.ensembl.org\n\nEach Ensembl release has an archive REST endpoint (e.g. `https:\u002F\u002Fe110.rest.ensembl.org`) for reproducibility.\n\n# Ensembl REST\n\n**\"Pull Ensembl-native gene \u002F transcript \u002F variant data programmatically\"** -> Ensembl REST is distinct from NCBI Entrez and BioMart. It is the right answer for: stable Ensembl IDs, transcript \u002F exon structure, VEP (Variant Effect Predictor) annotation, Compara orthologs at vertebrate scale, regulatory feature annotation, and any workflow rooted in Ensembl's coordinate system.\n\nTwo facts dominate Ensembl REST work: (1) the **15 req\u002Fsec \u002F 55,000 req\u002Fhour rate limit** — high enough for hundreds of queries, low enough that bulk work (>5,000) belongs in BioMart instead; (2) **versioned archive endpoints** — `https:\u002F\u002Fe110.rest.ensembl.org` pins to release 110 for reproducibility, while `https:\u002F\u002Frest.ensembl.org` follows the current release.\n\n- Python: `requests.get('https:\u002F\u002Frest.ensembl.org\u002F...')`\n- Web: https:\u002F\u002Frest.ensembl.org (interactive doc with try-it-now)\n- R: `biomaRt` for bulk (see `biomart-queries`); REST via `httr`\n\n## Required Setup\n\n```python\nimport requests\nimport time\n\nBASE = 'https:\u002F\u002Frest.ensembl.org'\nHEADERS = {'Accept': 'application\u002Fjson'}\nSLEEP = 0.07   # 15 req\u002Fsec ceiling\n```\n\nNo API key required. Respect `Retry-After` header on 429.\n\n## Ensembl divisions\n\nEnsembl is divided by clade. Different REST hosts:\n\n| Division | Host | Scope |\n|---|---|---|\n| Vertebrates | https:\u002F\u002Frest.ensembl.org | Human, mouse, fish, etc. (the \"main\" Ensembl) |\n| Plants | https:\u002F\u002Frest.ensembl.org (plants division also accessible) | Arabidopsis, rice, etc. via Ensembl Genomes |\n| Fungi | https:\u002F\u002Frest.ensemblgenomes.org | Yeasts, Aspergillus, etc. |\n| Metazoa | https:\u002F\u002Frest.ensemblgenomes.org | Insects, nematodes, etc. |\n| Bacteria | https:\u002F\u002Frest.ensemblgenomes.org | Limited (most bacteria in NCBI) |\n\nFor non-vertebrate work, check `ensemblgenomes.org` mirrors. As of 2024, Ensembl Genomes was being consolidated; check current host.\n\n## Version pinning\n\n| URL | Behavior |\n|---|---|\n| `https:\u002F\u002Frest.ensembl.org` | Current release (rolling) |\n| `https:\u002F\u002Fe110.rest.ensembl.org` | Pinned to release 110 |\n| `https:\u002F\u002Fe111.rest.ensembl.org` | Pinned to release 111 |\n| `https:\u002F\u002Fgrch37.rest.ensembl.org` | Pinned to GRCh37 (legacy assembly) |\n\nFor any published analysis, pin the release. Ensembl releases change gene model versions, exon coordinates, and transcript annotations — re-running a pipeline a year later against the live endpoint may produce different results.\n\n## Major endpoint groups\n\n| Group | Example | Purpose |\n|---|---|---|\n| Lookup | `\u002Flookup\u002Fsymbol\u002Fhuman\u002FBRCA1` | Resolve symbol or ID to stable record |\n| Sequence | `\u002Fsequence\u002Fid\u002F{id}` | DNA\u002Fprotein sequence for ID |\n| Cross References | `\u002Fxrefs\u002Fsymbol\u002Fhuman\u002FBRCA1` | Cross-refs to other DBs |\n| Homology \u002F Compara | `\u002Fhomology\u002Fsymbol\u002Fhuman\u002FBRCA1` | Orthologs and paralogs |\n| Gene Tree | `\u002Fgenetree\u002Fid\u002F{tree_id}` | Compara gene tree |\n| VEP | `\u002Fvep\u002Fhuman\u002Fregion\u002F{region}\u002F{allele}` | Variant effect prediction |\n| Overlap | `\u002Foverlap\u002Fid\u002F{id}` or `\u002Foverlap\u002Fregion\u002F{region}` | Genes\u002Fregulatory in interval |\n| Regulatory | `\u002Fregulatory\u002Fspecies\u002F{species}\u002Ffeature\u002F{id}` | Regulatory features |\n| Variant | `\u002Fvariation\u002F{species}\u002F{id}` | dbSNP \u002F 1000G \u002F ClinVar via Ensembl |\n| LD | `\u002Fld\u002F{species}\u002Fpairwise\u002F{var1}\u002F{var2}` | LD between variants |\n| GA4GH | `\u002Fga4gh\u002F...` | GA4GH-compliant subset |\n\nFull reference: https:\u002F\u002Frest.ensembl.org (interactive).\n\n## The symbol-vs-ID stability problem\n\nGene symbols are unstable (MARCH1 -> MARCHF1 in 2020 due to Excel autocorrect; SEPT* family also renamed). Ensembl Gene IDs (ENSG...) are stable across releases when the gene model is preserved.\n\n**Best practice:**\n1. Resolve symbol -> Ensembl ID once at pipeline start: `\u002Flookup\u002Fsymbol\u002F{species}\u002F{symbol}`.\n2. Persist the Ensembl ID.\n3. Run downstream queries by ID, not symbol.\n\nSymbol-based endpoints are convenient for interactive use; ID-based endpoints are for reproducible pipelines.\n\n## Rate-limit math\n\n| Limit | Value |\n|---|---|\n| Burst | 15 req\u002Fsec |\n| Hourly | 55,000 req\u002Fhour |\n| Concurrent | Not enforced; courtesy 1-2 |\n\nRespect `Retry-After` header on HTTP 429. For >5,000 queries, switch to BioMart bulk export (see `biomart-queries`) — BioMart has separate, more permissive limits.\n\n## VEP (Variant Effect Predictor)\n\nVEP via REST is the right call for ad hoc variant annotation. For batch variant annotation (>1000 variants), download VEP and run locally (`variant-calling\u002Fvariant-annotation` skill).\n\nREST modes:\n- `\u002Fvep\u002F{species}\u002Fregion\u002F{region}\u002F{allele}` — single variant by coordinate\n- `\u002Fvep\u002F{species}\u002Fid\u002F{variant_id}` — by dbSNP \u002F Ensembl variant ID\n- `\u002Fvep\u002F{species}\u002Fhgvs\u002F{hgvs_notation}` — by HGVS notation\n\nVEP returns rich annotation: consequence (missense, synonymous, intron), SIFT\u002FPolyPhen scores, gnomAD frequencies (if available), ClinVar significance.\n\n## Compara homology\n\nCompara orthology calls via Ensembl REST are covered in detail in `ortholog-inference` (database-access view). The relevant endpoint:\n\n- `\u002Fhomology\u002Fsymbol\u002F{species}\u002F{symbol}` — all orthologs across Ensembl species\n- `\u002Fhomology\u002Fid\u002F{ensembl_id}` — same, by ID\n- `?target_species=` to restrict to one target\n- `?type=orthologues` or `paralogues` to filter\n\n## Code patterns\n\n### Symbol -> stable Ensembl Gene ID\n\n**Goal:** Resolve a gene symbol to its current Ensembl Gene ID once, then use the ID for all downstream queries.\n\n**Approach:** `\u002Flookup\u002Fsymbol\u002F{species}\u002F{symbol}` returns the canonical record.\n\n**Reference (requests 2.31+):**\n```python\nimport requests\nimport time\n\nBASE = 'https:\u002F\u002Frest.ensembl.org'\nHEADERS = {'Accept': 'application\u002Fjson'}\n\n\ndef get_with_retry(url, params=None, max_retries=3):\n    for attempt in range(max_retries):\n        r = requests.get(url, params=params, headers=HEADERS)\n        if r.status_code == 429:\n            time.sleep(int(r.headers.get('Retry-After', '5')))\n            continue\n        r.raise_for_status()\n        return r\n    raise RuntimeError(f'Failed after {max_retries} retries')\n\n\ndef symbol_to_ensembl(species, symbol):\n    r = get_with_retry(f'{BASE}\u002Flookup\u002Fsymbol\u002F{species}\u002F{symbol}')\n    return r.json()\n\n\ninfo = symbol_to_ensembl('human', 'BRCA1')\nprint(f'  Ensembl Gene ID: {info[\"id\"]}')\nprint(f'  Biotype:         {info[\"biotype\"]}')\nprint(f'  Chromosome:      {info[\"seq_region_name\"]}:{info[\"start\"]}-{info[\"end\"]}')\nprint(f'  Strand:          {info[\"strand\"]}')\n```\n\n### Sequence retrieval by Ensembl ID\n\n```python\ndef get_sequence(ensembl_id, seq_type='cdna'):\n    '''seq_type: cdna, cds, protein, genomic'''\n    r = get_with_retry(f'{BASE}\u002Fsequence\u002Fid\u002F{ensembl_id}',\n                       params={'type': seq_type, 'content-type': 'application\u002Fjson'})\n    return r.json()\n\n\nprot = get_sequence('ENSG00000139618', seq_type='protein')\nprint(f'  Length: {len(prot[\"seq\"])} aa')\n```\n\n### Overlap: what genes are in this region\n\n```python\ndef genes_in_region(species, region):\n    '''region as \"chr:start-end\" e.g. \"17:43000000-44000000\".'''\n    r = get_with_retry(f'{BASE}\u002Foverlap\u002Fregion\u002F{species}\u002F{region}',\n                       params={'feature': 'gene'})\n    return r.json()\n\n\nfor g in genes_in_region('human', '17:43000000-43200000'):\n    print(f'  {g[\"external_name\"]:\u003C12} {g[\"id\"]} {g[\"biotype\"]:\u003C20} {g[\"start\"]}-{g[\"end\"]}')\n```\n\n### VEP for a single variant\n\n**Goal:** Get full annotation for a variant by coordinate.\n\n**Approach:** `\u002Fvep\u002F{species}\u002Fregion\u002F{region}\u002F{allele}` returns transcript consequences, SIFT\u002FPolyPhen, frequencies.\n\n**Reference (Ensembl REST release 110+):**\n```python\ndef vep_region(species, region, allele):\n    r = get_with_retry(f'{BASE}\u002Fvep\u002F{species}\u002Fregion\u002F{region}\u002F{allele}')\n    return r.json()\n\n\n# BRCA1 missense variant in GRCh38 coordinates (rest.ensembl.org defaults to GRCh38);\n# for GRCh37 coords use https:\u002F\u002Fgrch37.rest.ensembl.org instead.\nresults = vep_region('human', '17:43044295-43044295:1', 'A')\nif results:\n    for tc in results[0].get('transcript_consequences', [])[:5]:\n        print(f'  {tc[\"gene_symbol\"]:\u003C8} {tc[\"consequence_terms\"]}')\n        if 'sift_prediction' in tc:\n            print(f'    SIFT: {tc[\"sift_prediction\"]} ({tc.get(\"sift_score\", \"?\")})')\n```\n\n### Compara orthologs (Compara via REST)\n\n```python\ndef orthologs(species, symbol, target_species=None):\n    params = {'type': 'orthologues'}\n    if target_species:\n        params['target_species'] = target_species\n    r = get_with_retry(f'{BASE}\u002Fhomology\u002Fsymbol\u002F{species}\u002F{symbol}', params=params)\n    return r.json()['data'][0]['homologies']\n\n\nfor o in orthologs('human', 'BRCA1', target_species='mouse'):\n    print(f'  {o[\"target\"][\"species\"]:\u003C15} {o[\"target\"][\"id\"]}  type={o[\"type\"]}  confidence={o.get(\"confidence\")}')\n```\n\n### Batch lookup with rate-limit handling\n\n```python\ndef batch_symbols(species, symbols):\n    out = {}\n    for sym in symbols:\n        try:\n            out[sym] = symbol_to_ensembl(species, sym)\n        except requests.HTTPError as e:\n            out[sym] = {'error': str(e)}\n        time.sleep(0.07)  # 15 req\u002Fsec ceiling\n    return out\n```\n\n### Archive endpoint for reproducibility\n\n```python\n# Pin to release 110\nARCHIVE = 'https:\u002F\u002Fe110.rest.ensembl.org'\nr = requests.get(f'{ARCHIVE}\u002Flookup\u002Fsymbol\u002Fhuman\u002FBRCA1', headers={'Accept': 'application\u002Fjson'})\nprint(r.json()['id'])\n# Re-runs against e110 in 2030 will return the same Gene ID even if the live release has moved on.\n```\n\n### LD between two variants\n\n```python\ndef ld_pairwise(species, var1, var2, population='1000GENOMES:phase_3:CEU'):\n    r = get_with_retry(f'{BASE}\u002Fld\u002F{species}\u002Fpairwise\u002F{var1}\u002F{var2}',\n                       params={'population_name': population})\n    return r.json()\n```\n\n## Failure modes\n\n### Symbol-based pipeline breaks on HGNC rename\n- **Trigger:** `\u002Flookup\u002Fsymbol\u002Fhuman\u002FMARCH1` after the 2020 rename.\n- **Mechanism:** HGNC renamed Excel-autocorrect-affected genes; Ensembl mirrors the rename.\n- **Symptom:** 404 or wrong gene returned.\n- **Fix:** Resolve symbol to Ensembl Gene ID once at pipeline start; use ID downstream.\n\n### No version pinning, results drift\n- **Trigger:** Re-running a pipeline against `https:\u002F\u002Frest.ensembl.org` a year later.\n- **Mechanism:** Live endpoint follows current release; gene models update quarterly.\n- **Symptom:** Different transcript coordinates, exon counts, sometimes Gene ID changes.\n- **Fix:** Pin to an archive endpoint (`https:\u002F\u002Fe110.rest.ensembl.org`) for reproducibility.\n\n### Rate-limit cascade\n- **Trigger:** Loop of 5,000 REST calls without sleep.\n- **Mechanism:** 15 req\u002Fsec ceiling; 429 with Retry-After.\n- **Symptom:** Pipeline stalls; cascade of failures.\n- **Fix:** Sleep 0.07s between calls; honor Retry-After; for >5K queries use BioMart bulk export.\n\n### VEP for bulk variants\n- **Trigger:** VEP REST for 100K variants.\n- **Mechanism:** REST is per-variant; rate-limit makes this infeasible.\n- **Symptom:** Days-long runtime; many 429s.\n- **Fix:** Download VEP and run locally (`variant-calling\u002Fvariant-annotation` skill); reserve REST for ad hoc \u003C1K variants.\n\n### Wrong species name\n- **Trigger:** Using `Homo_sapiens` instead of `human`, or arbitrary capitalization.\n- **Mechanism:** Ensembl species names are lowercase with underscores or common names; case matters.\n- **Symptom:** 404 or empty result.\n- **Fix:** Use `https:\u002F\u002Frest.ensembl.org\u002Finfo\u002Fspecies` to enumerate valid names.\n\n### Non-vertebrate species not in vertebrate host\n- **Trigger:** Querying Arabidopsis on `rest.ensembl.org`.\n- **Mechanism:** Plants live in Ensembl Genomes (`rest.ensemblgenomes.org`) as of 2024 (consolidation ongoing).\n- **Symptom:** 404 or species not recognized.\n- **Fix:** Check the right division host; use the lookup endpoint `info\u002Fdivisions` to confirm.\n\n### Archive endpoint TLS \u002F connectivity\n- **Trigger:** Older archive endpoints (e80, e90) gradually decommissioned.\n- **Mechanism:** Very old archives are retired ~5 years after release.\n- **Symptom:** DNS failure or 503.\n- **Fix:** Check the current archive list at https:\u002F\u002Fwww.ensembl.org\u002Finfo\u002Fwebsite\u002Farchives\u002Findex.html.\n\n## Common errors\n\n| Error \u002F symptom | Cause | Solution |\n|---|---|---|\n| `404` on symbol lookup | HGNC rename or wrong species | Resolve to Ensembl ID; check species code |\n| HTTP 429 | Rate limit | Sleep per Retry-After; cap to 15 req\u002Fsec |\n| Different results 6 months later | No version pinning | Use archive endpoint (`eXX.rest.ensembl.org`) |\n| `404` on non-vertebrate | Wrong host division | Switch to `rest.ensemblgenomes.org` |\n| VEP infeasible bulk | REST is per-variant | Local VEP for bulk |\n| Old archive 503 | Decommissioned | Use a current archive release |\n\n## References\n\n- Yates AD, Allen J, Amode RM, et al. (2022) Ensembl Genomes 2022: an expanding genome resource for non-vertebrates. *Nucleic Acids Res* 50:D996-D1003.\n- Martin FJ, Amode MR, Aneja A, et al. (2023) Ensembl 2023. *Nucleic Acids Res* 51:D933-D941.\n- McLaren W, Gil L, Hunt SE, et al. (2016) The Ensembl Variant Effect Predictor. *Genome Biol* 17:122.\n- Yates A, Beal K, Keenan S, et al. (2015) The Ensembl REST API: Ensembl data for any language. *Bioinformatics* 31:143-145.\n\n## Related Skills\n\n- biomart-queries - Ensembl BioMart for bulk (>5K) ID mapping\n- ortholog-inference - Compara orthologs via Ensembl REST and other resources\n- uniprot-access - Cross-reference Ensembl IDs in UniProt entries\n- variant-calling\u002Fvariant-annotation - Local VEP for bulk variant annotation\n- ncbi-datasets-cli - NCBI alternative for genome \u002F gene data\n- entrez-search - NCBI alternative for non-Ensembl queries\n","## Version Compatibility\n\nReference examples tested with: requests 2.31+, Ensembl REST API (release 110+); Ensembl release schedule is roughly quarterly\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- Python: `pip show requests`\n- API surface: check release notes at https:\u002F\u002Frest.ensembl.org\n\nEach Ensembl release has an archive REST endpoint (e.g. `https:\u002F\u002Fe110.rest.ensembl.org`) for reproducibility.\n\n# Ensembl REST\n\n**\"Pull Ensembl-native gene \u002F transcript \u002F variant data programmatically\"** -> Ensembl REST is distinct from NCBI Entrez and BioMart. It is the right answer for: stable Ensembl IDs, transcript \u002F exon structure, VEP (Variant Effect Predictor) annotation, Compara orthologs at vertebrate scale, regulatory feature annotation, and any workflow rooted in Ensembl's coordinate system.\n\nTwo facts dominate Ensembl REST work: (1) the **15 req\u002Fsec \u002F 55,000 req\u002Fhour rate limit** — high enough for hundreds of queries, low enough that bulk work (>5,000) belongs in BioMart instead; (2) **versioned archive endpoints** — `https:\u002F\u002Fe110.rest.ensembl.org` pins to release 110 for reproducibility, while `https:\u002F\u002Frest.ensembl.org` follows the current release.\n\n- Python: `requests.get('https:\u002F\u002Frest.ensembl.org\u002F...')`\n- Web: https:\u002F\u002Frest.ensembl.org (interactive doc with try-it-now)\n- R: `biomaRt` for bulk (see `biomart-queries`); REST via `httr`\n\n## Required Setup\n\n```python\nimport requests\nimport time\n\nBASE = 'https:\u002F\u002Frest.ensembl.org'\nHEADERS = {'Accept': 'application\u002Fjson'}\nSLEEP = 0.07   # 15 req\u002Fsec ceiling\n```\n\nNo API key required. Respect `Retry-After` header on 429.\n\n## Ensembl divisions\n\nEnsembl is divided by clade. Different REST hosts:\n\n| Division | Host | Scope |\n|---|---|---|\n| Vertebrates | https:\u002F\u002Frest.ensembl.org | Human, mouse, fish, etc. (the \"main\" Ensembl) |\n| Plants | https:\u002F\u002Frest.ensembl.org (plants division also accessible) | Arabidopsis, rice, etc. via Ensembl Genomes |\n| Fungi | https:\u002F\u002Frest.ensemblgenomes.org | Yeasts, Aspergillus, etc. |\n| Metazoa | https:\u002F\u002Frest.ensemblgenomes.org | Insects, nematodes, etc. |\n| Bacteria | https:\u002F\u002Frest.ensemblgenomes.org | Limited (most bacteria in NCBI) |\n\nFor non-vertebrate work, check `ensemblgenomes.org` mirrors. As of 2024, Ensembl Genomes was being consolidated; check current host.\n\n## Version pinning\n\n| URL | Behavior |\n|---|---|\n| `https:\u002F\u002Frest.ensembl.org` | Current release (rolling) |\n| `https:\u002F\u002Fe110.rest.ensembl.org` | Pinned to release 110 |\n| `https:\u002F\u002Fe111.rest.ensembl.org` | Pinned to release 111 |\n| `https:\u002F\u002Fgrch37.rest.ensembl.org` | Pinned to GRCh37 (legacy assembly) |\n\nFor any published analysis, pin the release. Ensembl releases change gene model versions, exon coordinates, and transcript annotations — re-running a pipeline a year later against the live endpoint may produce different results.\n\n## Major endpoint groups\n\n| Group | Example | Purpose |\n|---|---|---|\n| Lookup | `\u002Flookup\u002Fsymbol\u002Fhuman\u002FBRCA1` | Resolve symbol or ID to stable record |\n| Sequence | `\u002Fsequence\u002Fid\u002F{id}` | DNA\u002Fprotein sequence for ID |\n| Cross References | `\u002Fxrefs\u002Fsymbol\u002Fhuman\u002FBRCA1` | Cross-refs to other DBs |\n| Homology \u002F Compara | `\u002Fhomology\u002Fsymbol\u002Fhuman\u002FBRCA1` | Orthologs and paralogs |\n| Gene Tree | `\u002Fgenetree\u002Fid\u002F{tree_id}` | Compara gene tree |\n| VEP | `\u002Fvep\u002Fhuman\u002Fregion\u002F{region}\u002F{allele}` | Variant effect prediction |\n| Overlap | `\u002Foverlap\u002Fid\u002F{id}` or `\u002Foverlap\u002Fregion\u002F{region}` | Genes\u002Fregulatory in interval |\n| Regulatory | `\u002Fregulatory\u002Fspecies\u002F{species}\u002Ffeature\u002F{id}` | Regulatory features |\n| Variant | `\u002Fvariation\u002F{species}\u002F{id}` | dbSNP \u002F 1000G \u002F ClinVar via Ensembl |\n| LD | `\u002Fld\u002F{species}\u002Fpairwise\u002F{var1}\u002F{var2}` | LD between variants |\n| GA4GH | `\u002Fga4gh\u002F...` | GA4GH-compliant subset |\n\nFull reference: https:\u002F\u002Frest.ensembl.org (interactive).\n\n## The symbol-vs-ID stability problem\n\nGene symbols are unstable (MARCH1 -> MARCHF1 in 2020 due to Excel autocorrect; SEPT* family also renamed). Ensembl Gene IDs (ENSG...) are stable across releases when the gene model is preserved.\n\n**Best practice:**\n1. Resolve symbol -> Ensembl ID once at pipeline start: `\u002Flookup\u002Fsymbol\u002F{species}\u002F{symbol}`.\n2. Persist the Ensembl ID.\n3. Run downstream queries by ID, not symbol.\n\nSymbol-based endpoints are convenient for interactive use; ID-based endpoints are for reproducible pipelines.\n\n## Rate-limit math\n\n| Limit | Value |\n|---|---|\n| Burst | 15 req\u002Fsec |\n| Hourly | 55,000 req\u002Fhour |\n| Concurrent | Not enforced; courtesy 1-2 |\n\nRespect `Retry-After` header on HTTP 429. For >5,000 queries, switch to BioMart bulk export (see `biomart-queries`) — BioMart has separate, more permissive limits.\n\n## VEP (Variant Effect Predictor)\n\nVEP via REST is the right call for ad hoc variant annotation. For batch variant annotation (>1000 variants), download VEP and run locally (`variant-calling\u002Fvariant-annotation` skill).\n\nREST modes:\n- `\u002Fvep\u002F{species}\u002Fregion\u002F{region}\u002F{allele}` — single variant by coordinate\n- `\u002Fvep\u002F{species}\u002Fid\u002F{variant_id}` — by dbSNP \u002F Ensembl variant ID\n- `\u002Fvep\u002F{species}\u002Fhgvs\u002F{hgvs_notation}` — by HGVS notation\n\nVEP returns rich annotation: consequence (missense, synonymous, intron), SIFT\u002FPolyPhen scores, gnomAD frequencies (if available), ClinVar significance.\n\n## Compara homology\n\nCompara orthology calls via Ensembl REST are covered in detail in `ortholog-inference` (database-access view). The relevant endpoint:\n\n- `\u002Fhomology\u002Fsymbol\u002F{species}\u002F{symbol}` — all orthologs across Ensembl species\n- `\u002Fhomology\u002Fid\u002F{ensembl_id}` — same, by ID\n- `?target_species=` to restrict to one target\n- `?type=orthologues` or `paralogues` to filter\n\n## Code patterns\n\n### Symbol -> stable Ensembl Gene ID\n\n**Goal:** Resolve a gene symbol to its current Ensembl Gene ID once, then use the ID for all downstream queries.\n\n**Approach:** `\u002Flookup\u002Fsymbol\u002F{species}\u002F{symbol}` returns the canonical record.\n\n**Reference (requests 2.31+):**\n```python\nimport requests\nimport time\n\nBASE = 'https:\u002F\u002Frest.ensembl.org'\nHEADERS = {'Accept': 'application\u002Fjson'}\n\n\ndef get_with_retry(url, params=None, max_retries=3):\n    for attempt in range(max_retries):\n        r = requests.get(url, params=params, headers=HEADERS)\n        if r.status_code == 429:\n            time.sleep(int(r.headers.get('Retry-After', '5')))\n            continue\n        r.raise_for_status()\n        return r\n    raise RuntimeError(f'Failed after {max_retries} retries')\n\n\ndef symbol_to_ensembl(species, symbol):\n    r = get_with_retry(f'{BASE}\u002Flookup\u002Fsymbol\u002F{species}\u002F{symbol}')\n    return r.json()\n\n\ninfo = symbol_to_ensembl('human', 'BRCA1')\nprint(f'  Ensembl Gene ID: {info[\"id\"]}')\nprint(f'  Biotype:         {info[\"biotype\"]}')\nprint(f'  Chromosome:      {info[\"seq_region_name\"]}:{info[\"start\"]}-{info[\"end\"]}')\nprint(f'  Strand:          {info[\"strand\"]}')\n```\n\n### Sequence retrieval by Ensembl ID\n\n```python\ndef get_sequence(ensembl_id, seq_type='cdna'):\n    '''seq_type: cdna, cds, protein, genomic'''\n    r = get_with_retry(f'{BASE}\u002Fsequence\u002Fid\u002F{ensembl_id}',\n                       params={'type': seq_type, 'content-type': 'application\u002Fjson'})\n    return r.json()\n\n\nprot = get_sequence('ENSG00000139618', seq_type='protein')\nprint(f'  Length: {len(prot[\"seq\"])} aa')\n```\n\n### Overlap: what genes are in this region\n\n```python\ndef genes_in_region(species, region):\n    '''region as \"chr:start-end\" e.g. \"17:43000000-44000000\".'''\n    r = get_with_retry(f'{BASE}\u002Foverlap\u002Fregion\u002F{species}\u002F{region}',\n                       params={'feature': 'gene'})\n    return r.json()\n\n\nfor g in genes_in_region('human', '17:43000000-43200000'):\n    print(f'  {g[\"external_name\"]:\u003C12} {g[\"id\"]} {g[\"biotype\"]:\u003C20} {g[\"start\"]}-{g[\"end\"]}')\n```\n\n### VEP for a single variant\n\n**Goal:** Get full annotation for a variant by coordinate.\n\n**Approach:** `\u002Fvep\u002F{species}\u002Fregion\u002F{region}\u002F{allele}` returns transcript consequences, SIFT\u002FPolyPhen, frequencies.\n\n**Reference (Ensembl REST release 110+):**\n```python\ndef vep_region(species, region, allele):\n    r = get_with_retry(f'{BASE}\u002Fvep\u002F{species}\u002Fregion\u002F{region}\u002F{allele}')\n    return r.json()\n\n\n# BRCA1 missense variant in GRCh38 coordinates (rest.ensembl.org defaults to GRCh38);\n# for GRCh37 coords use https:\u002F\u002Fgrch37.rest.ensembl.org instead.\nresults = vep_region('human', '17:43044295-43044295:1', 'A')\nif results:\n    for tc in results[0].get('transcript_consequences', [])[:5]:\n        print(f'  {tc[\"gene_symbol\"]:\u003C8} {tc[\"consequence_terms\"]}')\n        if 'sift_prediction' in tc:\n            print(f'    SIFT: {tc[\"sift_prediction\"]} ({tc.get(\"sift_score\", \"?\")})')\n```\n\n### Compara orthologs (Compara via REST)\n\n```python\ndef orthologs(species, symbol, target_species=None):\n    params = {'type': 'orthologues'}\n    if target_species:\n        params['target_species'] = target_species\n    r = get_with_retry(f'{BASE}\u002Fhomology\u002Fsymbol\u002F{species}\u002F{symbol}', params=params)\n    return r.json()['data'][0]['homologies']\n\n\nfor o in orthologs('human', 'BRCA1', target_species='mouse'):\n    print(f'  {o[\"target\"][\"species\"]:\u003C15} {o[\"target\"][\"id\"]}  type={o[\"type\"]}  confidence={o.get(\"confidence\")}')\n```\n\n### Batch lookup with rate-limit handling\n\n```python\ndef batch_symbols(species, symbols):\n    out = {}\n    for sym in symbols:\n        try:\n            out[sym] = symbol_to_ensembl(species, sym)\n        except requests.HTTPError as e:\n            out[sym] = {'error': str(e)}\n        time.sleep(0.07)  # 15 req\u002Fsec ceiling\n    return out\n```\n\n### Archive endpoint for reproducibility\n\n```python\n# Pin to release 110\nARCHIVE = 'https:\u002F\u002Fe110.rest.ensembl.org'\nr = requests.get(f'{ARCHIVE}\u002Flookup\u002Fsymbol\u002Fhuman\u002FBRCA1', headers={'Accept': 'application\u002Fjson'})\nprint(r.json()['id'])\n# Re-runs against e110 in 2030 will return the same Gene ID even if the live release has moved on.\n```\n\n### LD between two variants\n\n```python\ndef ld_pairwise(species, var1, var2, population='1000GENOMES:phase_3:CEU'):\n    r = get_with_retry(f'{BASE}\u002Fld\u002F{species}\u002Fpairwise\u002F{var1}\u002F{var2}',\n                       params={'population_name': population})\n    return r.json()\n```\n\n## Failure modes\n\n### Symbol-based pipeline breaks on HGNC rename\n- **Trigger:** `\u002Flookup\u002Fsymbol\u002Fhuman\u002FMARCH1` after the 2020 rename.\n- **Mechanism:** HGNC renamed Excel-autocorrect-affected genes; Ensembl mirrors the rename.\n- **Symptom:** 404 or wrong gene returned.\n- **Fix:** Resolve symbol to Ensembl Gene ID once at pipeline start; use ID downstream.\n\n### No version pinning, results drift\n- **Trigger:** Re-running a pipeline against `https:\u002F\u002Frest.ensembl.org` a year later.\n- **Mechanism:** Live endpoint follows current release; gene models update quarterly.\n- **Symptom:** Different transcript coordinates, exon counts, sometimes Gene ID changes.\n- **Fix:** Pin to an archive endpoint (`https:\u002F\u002Fe110.rest.ensembl.org`) for reproducibility.\n\n### Rate-limit cascade\n- **Trigger:** Loop of 5,000 REST calls without sleep.\n- **Mechanism:** 15 req\u002Fsec ceiling; 429 with Retry-After.\n- **Symptom:** Pipeline stalls; cascade of failures.\n- **Fix:** Sleep 0.07s between calls; honor Retry-After; for >5K queries use BioMart bulk export.\n\n### VEP for bulk variants\n- **Trigger:** VEP REST for 100K variants.\n- **Mechanism:** REST is per-variant; rate-limit makes this infeasible.\n- **Symptom:** Days-long runtime; many 429s.\n- **Fix:** Download VEP and run locally (`variant-calling\u002Fvariant-annotation` skill); reserve REST for ad hoc \u003C1K variants.\n\n### Wrong species name\n- **Trigger:** Using `Homo_sapiens` instead of `human`, or arbitrary capitalization.\n- **Mechanism:** Ensembl species names are lowercase with underscores or common names; case matters.\n- **Symptom:** 404 or empty result.\n- **Fix:** Use `https:\u002F\u002Frest.ensembl.org\u002Finfo\u002Fspecies` to enumerate valid names.\n\n### Non-vertebrate species not in vertebrate host\n- **Trigger:** Querying Arabidopsis on `rest.ensembl.org`.\n- **Mechanism:** Plants live in Ensembl Genomes (`rest.ensemblgenomes.org`) as of 2024 (consolidation ongoing).\n- **Symptom:** 404 or species not recognized.\n- **Fix:** Check the right division host; use the lookup endpoint `info\u002Fdivisions` to confirm.\n\n### Archive endpoint TLS \u002F connectivity\n- **Trigger:** Older archive endpoints (e80, e90) gradually decommissioned.\n- **Mechanism:** Very old archives are retired ~5 years after release.\n- **Symptom:** DNS failure or 503.\n- **Fix:** Check the current archive list at https:\u002F\u002Fwww.ensembl.org\u002Finfo\u002Fwebsite\u002Farchives\u002Findex.html.\n\n## Common errors\n\n| Error \u002F symptom | Cause | Solution |\n|---|---|---|\n| `404` on symbol lookup | HGNC rename or wrong species | Resolve to Ensembl ID; check species code |\n| HTTP 429 | Rate limit | Sleep per Retry-After; cap to 15 req\u002Fsec |\n| Different results 6 months later | No version pinning | Use archive endpoint (`eXX.rest.ensembl.org`) |\n| `404` on non-vertebrate | Wrong host division | Switch to `rest.ensemblgenomes.org` |\n| VEP infeasible bulk | REST is per-variant | Local VEP for bulk |\n| Old archive 503 | Decommissioned | Use a current archive release |\n\n## References\n\n- Yates AD, Allen J, Amode RM, et al. (2022) Ensembl Genomes 2022: an expanding genome resource for non-vertebrates. *Nucleic Acids Res* 50:D996-D1003.\n- Martin FJ, Amode MR, Aneja A, et al. (2023) Ensembl 2023. *Nucleic Acids Res* 51:D933-D941.\n- McLaren W, Gil L, Hunt SE, et al. (2016) The Ensembl Variant Effect Predictor. *Genome Biol* 17:122.\n- Yates A, Beal K, Keenan S, et al. (2015) The Ensembl REST API: Ensembl data for any language. *Bioinformatics* 31:143-145.\n\n## Related Skills\n\n- biomart-queries - Ensembl BioMart for bulk (>5K) ID mapping\n- ortholog-inference - Compara orthologs via Ensembl REST and other resources\n- uniprot-access - Cross-reference Ensembl IDs in UniProt entries\n- variant-calling\u002Fvariant-annotation - Local VEP for bulk variant annotation\n- ncbi-datasets-cli - NCBI alternative for genome \u002F gene data\n- entrez-search - NCBI alternative for non-Ensembl queries\n",{"name":5,"source":24,"license":15,"tool_type":25,"description":7,"imported_at":26,"source_path":27,"primary_tool":28,"source_repository":29},"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills","python","2026-09-20","database-access\u002Fensembl-rest\u002FSKILL.md","requests","GPTomics\u002FbioSkills","main","2d1750717747097b602acf30bd09a7cbd4b4c6ea","awesome_skills\u002Fbiology\u002Fbio-ensembl-rest","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous","2026-11-09 11:45:36",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-ensembl-rest",{"tool":42,"command":43},"bunx","bunx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-ensembl-rest",{"tool":45,"command":46},"pnpm","pnpm dlx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-ensembl-rest","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-ensembl-rest\u002FSKILL.md",true,[50,56,60,64],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"examples\u002Fcompara_homology.py","SCRIPT","脚本",2700,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-ensembl-rest\u002Fexamples\u002Fcompara_homology.py",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"examples\u002Flookup_and_overlap.py",2766,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-ensembl-rest\u002Fexamples\u002Flookup_and_overlap.py",{"path":61,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":62,"sourceHtmlUrl":63},"examples\u002Fvep_annotation.py",2623,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-ensembl-rest\u002Fexamples\u002Fvep_annotation.py",{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"usage-guide.md","REFERENCE","参考文档",4532,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-ensembl-rest\u002Fusage-guide.md",[71,79,86,93,100,107],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":78},"01M7FFFZPC2025JQQHPHDX154J","dei-assessment","Assess diversity, equity, and inclusion with metrics. TRIGGERS - Use when user needs help with dei-assessment related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fdei-assessment\u002FSKILL.md",[],[],"2026-11-16 10:05:34",{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":78},"01M7FFFWN8H4WA7A6Y398QKB6J","dei-action-plan","Create DEI action plans with goals and initiatives. TRIGGERS - Use when user needs help with dei-action-plan related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fdei-action-plan\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":78},"01M7FFFSHTM0QZRVZ2NRJTJ0PY","culture-fit-assessment","Design culture add assessment processes. TRIGGERS - Use when user needs help with culture-fit-assessment related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fculture-fit-assessment\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":78},"01M7FFFMA12RKEQA38KHJSXXPS","cowork-to-code-bridge","Use an already-installed, independently verified cowork-to-code bridge to run narrowly approved actions on the user's own macOS, Linux, or WSL2 machine through a local file queue.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcowork-to-code-bridge\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":78},"01M7FFFH1F6M8YRGW5V487GH1K","counter-offer-response","Draft counter-offer responses for retention. TRIGGERS - Use when user needs help with counter-offer-response related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcounter-offer-response\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":78},"01M7FFFDGEHV8Y7J9N40HZXW52","continuous-feedback-system","Design continuous feedback systems. TRIGGERS - Use when user needs help with continuous-feedback-system related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcontinuous-feedback-system\u002FSKILL.md",[],[]]