Variant-level API Access

Feature Availability

Variant-level API access is enabled on demand and supports human GRCh38 (g1k_v38) samples only. If you'd like to query variant-level data through Gencove's API, please contact Gencove support to have it enabled for your organization.

Overview

The variant-level API lets your application read individual genetic variants directly from a sample's imputed VCF — without downloading the multi-gigabyte VCF file. You query a sample by a single genomic position, a coordinate range, or a list of rsIDs, and Gencove returns just the matching variant records as JSON.

This is useful when you need a handful of specific variants — for example a pharmacogenomic marker, an APOE genotype, or an MTHFR variant — rather than the whole genome.

Key Concepts

• Sample: A single genetic sample in Gencove, identified by a unique sample_id (a UUID). Variant queries are made against a sample_id.
• Imputed VCF: The whole-genome variant file Gencove produces for a sample once analysis completes. The variant-level API reads directly from this file.
• Genomic coordinate: A chromosome plus a 1-based position on the GRCh38 (h38) human reference. Chromosomes use the chr prefix — chr1–chr22, chrX, chrY, chrM.
• rsID: A dbSNP reference SNP identifier, e.g. rs429358. Gencove resolves an rsID to its genomic coordinate for you.
• Variant record: A single entry from the VCF — chromosome, position, reference and alternate alleles, the sample's genotype, and quality/annotation fields.

How It Works

You make an authenticated GET request to the variant endpoint for a sample, supplying exactly one query mode — a point, a range, or a list of rsIDs. Gencove reads the matching variant records straight from that sample's imputed VCF and returns them as JSON. No large-file download or local VCF parsing is required.

Getting Started

Get Your API Key

To make requests to Gencove's API, you'll need an API key. This key authenticates your application and should be kept secure (treat it like a secret or a password).

To generate an API key:

1. Log in to your Gencove account at web.gencove.com
2. In the left sidebar, click on Account
3. Navigate to the API Keys tab
4. Click the Generate new API key button
5. Copy the generated API key and store it securely

Security Best Practice: For production use, consider creating a separate Gencove user with Analyst level privileges specifically for API access, and use that user's API key. This follows the principle of least privilege and makes it easier to manage access if needed.

Keep Your API Key Secret

Your API key provides access to your Gencove account. Never commit it to version control, never share it publicly, never expose it in client-side code. Store it in a secure secrets management system. If your key gets exposed, make sure to revoke it immediately and generate a new one.

Requirements

Variant-level queries are available for samples that:

• were processed with Gencove's human GRCh38 (g1k_v38) pipeline;
• have completed analysis, so the imputed VCF is available;
• are not archived — archived samples must be restored before they can be queried.

A request against a sample that does not meet these requirements returns a 400 error explaining why.

Querying Variants

API Endpoint: GET https://api.gencove.com/api/v2/sample-genomic-variants/{sample_id}

Authentication: Include your API key in the Authorization header: Authorization: Api-Key $GENCOVE_API_KEY

Each request uses exactly one of three query modes:

Mode	Query parameters	Use it to…
Point	chromosome + position	Look up a single genomic position
Range	chromosome + start_position + end_position	List every variant in a coordinate window
rsID	rsid (comma-separated)	Look up one or more variants by dbSNP rsID

Combining modes in a single request returns a 400 error.

Point Query

Look up a single position. Here, the APOE variant rs429358 at chr19:44908684:

cURLPython

curl "https://api.gencove.com/api/v2/sample-genomic-variants/$SAMPLE_ID?chromosome=chr19&position=44908684" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY"

import os

import requests

API_KEY = os.getenv("GENCOVE_API_KEY")
SAMPLE_ID = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

response = requests.get(
    f"https://api.gencove.com/api/v2/sample-genomic-variants/{SAMPLE_ID}",
    headers={"Authorization": f"Api-Key {API_KEY}"},
    params={"chromosome": "chr19", "position": 44908684},
)

variants = response.json()["results"]

Range Query

List every variant in a coordinate window. The window must span 100 kb or less. Here, the region around the APOE gene:

cURLPython

curl "https://api.gencove.com/api/v2/sample-genomic-variants/$SAMPLE_ID?chromosome=chr19&start_position=44905000&end_position=44910000" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY"

import os

import requests

API_KEY = os.getenv("GENCOVE_API_KEY")
SAMPLE_ID = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

response = requests.get(
    f"https://api.gencove.com/api/v2/sample-genomic-variants/{SAMPLE_ID}",
    headers={"Authorization": f"Api-Key {API_KEY}"},
    params={
        "chromosome": "chr19",
        "start_position": 44905000,
        "end_position": 44910000,
    },
)

variants = response.json()["results"]

rsID Query

Look up variants by dbSNP rsID — Gencove resolves each rsID to its genomic coordinate. Supply up to 50 comma-separated rsIDs. Here, both APOE-defining variants (rs429358, rs7412) plus the MTHFR C677T variant (rs1801133):

cURLPython

curl "https://api.gencove.com/api/v2/sample-genomic-variants/$SAMPLE_ID?rsid=rs429358,rs7412,rs1801133" \
  -H "Authorization: Api-Key $GENCOVE_API_KEY"

import os

import requests

API_KEY = os.getenv("GENCOVE_API_KEY")
SAMPLE_ID = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

response = requests.get(
    f"https://api.gencove.com/api/v2/sample-genomic-variants/{SAMPLE_ID}",
    headers={"Authorization": f"Api-Key {API_KEY}"},
    params={"rsid": "rs429358,rs7412,rs1801133"},
)

variants = response.json()["results"]

An rsID that Gencove cannot resolve, or that is not present in the sample's VCF, is simply omitted from the results — the request still succeeds with a 200 response.

Query Parameters

Parameter	Type	Description
chromosome	string	GRCh38 contig name with the chr prefix — chr1–chr22, chrX, chrY, chrM. Required for point and range queries.
position	integer	1-based genomic position. Point queries only.
start_position	integer	1-based start of the range, inclusive. Range queries only.
end_position	integer	1-based end of the range, inclusive. Range queries only.
rsid	string	One or more dbSNP rsIDs, comma-separated (e.g. rs429358,rs7412). rsID queries only.
limit	integer	Maximum number of variants to return in one page. Optional.
offset	integer	Number of variants to skip — used for pagination. Optional.

Response

A successful request returns 200 OK with a paginated JSON body: meta holds the result count, and results is the list of variant records.

{
  "meta": {
    "count": 1
  },
  "results": [
    {
      "chromosome": "chr19",
      "position": 44908684,
      "rsid": "rs429358",
      "ref": "T",
      "alt": ["C"],
      "genotype": {"GT": "0|1", "DS": "1", "GP": "0,1,0"},
      "quality": null,
      "info": {"RAF": "0.15"}
    }
  ]
}

Each variant record contains:

Field	Type	Description
chromosome	string	GRCh38 contig, chr-prefixed.
position	integer	1-based position on GRCh38.
rsid	string · nullable	dbSNP rsID, or null if the variant has none.
ref	string	Reference allele.
alt	array of strings	Alternate allele(s).
genotype	object · nullable	The sample's per-variant VCF FORMAT fields keyed by name — e.g. GT (genotype), DS (dosage), GP (genotype probabilities). null if the record carries no genotype data.
quality	number · nullable	VCF QUAL score, or null.
info	object	VCF INFO annotations as key/value pairs.

In a genotype, the GT allele indexes reference the alleles: 0 is ref, 1 is the first alt, 2 the second, and so on. For example, GT: "0|1" with ref: "T" and alt: ["C"] means the sample carries one T copy and one C copy.

Limits

To keep queries fast, the following per-request limits apply:

Limit	Value
Maximum range span	100 kb (end_position − start_position)
Maximum rsIDs per request	50
Request rate	5 requests per second

Exceeding the range or rsID limit returns a 400 error; exceeding the rate limit returns 429 Too Many Requests.

Support

If you have questions about variant-level API access or run into any issues:

• API Reference
• Gencove Support