List every gnomAD variant in a gene, transcript, or region with allele frequencies, filtering allele frequencies, zygosity counts, predicted consequences with LOFTEE's loss-of-function call, and QC status, optionally filtered to one consequence class (lof, missense, synonymous, other), a LOFTEE confidence (lof_confidence HC or LC), a maximum allele frequency, and/or a maximum filtering allele frequency (faf95_max, the value to test against a disease threshold such as ACMG/AMP BA1 or BS1). Pass annotations: true to add each row's HGVS c. and p. notation, LOFTEE filter and flags, and rsIDs. Every row carries its exome and genome QC filters and a qc_status; qc_filtered counts the matching variants that failed QC in every callset carrying them (often AC0, no high-quality carrier, at AF 0), which gnomAD's browser hides by default — read them as low-confidence, not observed variants, or pass pass_only to drop them. Each call returns one page: up to limit matching variants from offset, in gnomAD's genomic order, with total counting every match; pass next_offset as offset until it is null. gnomAD lists a target only whole, so each page re-fetches the whole target — page a large gene with filters and a large limit. At offset 0, a result too large to inline is also staged on a DataCanvas table named gene_variants holding every matching variant, returned as canvas_id and table_name — call gnomad_dataframe_describe for its columns, then gnomad_dataframe_query to rank by AF, count by consequence, or group across every row rather than one page. A result that fits inline stages no table unless canvas_id is supplied, and a page past offset 0 never stages. Supply exactly one of gene, transcript_id, or region. Echoes the resolved target, the row filters, and the effective dataset and build.
Data source: gnomAD (Broad Institute) — https://gnomad.broadinstitute.org/
View input schema
{
"type": "object",
"properties": {
"gene": {
"description": "Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene. Mitochondrial genes (e.g. MT-TL1) are not served. Mutually exclusive with transcript_id and region; blank means omitted.",
"anyOf": [
{
"type": "string",
"minLength": 2,
"description": "Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene."
},
{
"type": "string",
"maxLength": 0,
"description": "Blank — the gene is treated as omitted."
}
]
},
"transcript_id": {
"description": "Ensembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region; blank means omitted.",
"type": "string"
},
"region": {
"description": "Genomic region chrom-start-stop (1-based inclusive, e.g. 1-55039447-55064852): chromosome 1–22, X, or Y with an optional chr prefix (mitochondrial regions are not served), a span (stop − start) under 2,500,000 bp, and at most ~30,000 variants. Mutually exclusive with gene and transcript_id.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:chr)?[0-9A-Z]+-\\d+-\\d+$",
"description": "Genomic region chrom-start-stop (1-based inclusive, e.g. 1-55039447-55064852) on chromosome 1–22, X, or Y, optional chr prefix."
}
]
},
"consequence_class": {
"description": "Keep only variants in this gnomAD consequence category, read from each row's consequence: lof (pLoF) is transcript_ablation, splice_acceptor_variant, splice_donor_variant, stop_gained, frameshift_variant; missense (missense / inframe indel) is missense_variant, stop_lost, start_lost, inframe_insertion, inframe_deletion; synonymous is synonymous_variant; other is every other term and a null consequence. Omit to return all classes.",
"type": "string",
"enum": [
"lof",
"missense",
"synonymous",
"other"
]
},
"lof_confidence": {
"description": "Keep only variants whose lof — LOFTEE's call on the row's transcript_id — equals this: HC high-confidence or LC low-confidence. A row with lof null or OS matches neither. consequence_class lof reads the consequence term instead, so it keeps LoF terms LOFTEE did not call. Omit to keep every call.",
"type": "string",
"enum": [
"HC",
"LC"
]
},
"max_af": {
"description": "Keep only variants with allele frequency ≤ this value (0–1). Variants with null AF are always kept.",
"type": "number",
"minimum": 0,
"maximum": 1
},
"max_faf": {
"description": "Keep only variants whose filtering allele frequency (faf95_max) is ≤ this value (0–1) — the test against a disease threshold such as ACMG/AMP BA1 or BS1. Variants with a null faf95_max are always kept, and a notice counts them among total. gnomad_r3, its subsets, and exac list rows carry no FAF, so there it filters nothing and the notice says so.",
"type": "number",
"minimum": 0,
"maximum": 1
},
"pass_only": {
"description": "Keep only variants that passed gnomAD QC in at least one callset carrying them (qc_status pass), with the counts gnomAD's browser table shows by default: a row without joint data (every dataset but gnomad_r4, gnomad_r4_non_ukb included) reads ac, an, af, homozygote_count, hemizygote_count, and faf95_max from its passing callsets only, and max_af and max_faf filter on those values; gnomad_r4 rows keep their joint counts. The drop follows consequence_class, lof_confidence, max_af, and max_faf, and qc_filtered still counts the dropped rows. Omit to list every matching variant with its QC columns and a QC-failed callset's counts included — a single-position region then never reads as absent because of QC.",
"type": "boolean"
},
"annotations": {
"description": "Add five columns describing each row's transcript_id after every default column, on the rows and in the staged gene_variants table: hgvsc, hgvsp, lof_filter, lof_flags, and rsids (pipe-joined). Omitted or false, the rows and the table carry none of them. A column toggle, not a filter: it keeps every row and filters does not echo it. It widens every row by about a quarter and every page's re-fetch of the target from gnomAD by about as much.",
"type": "boolean"
},
"offset": {
"default": 0,
"description": "Zero-based position, among the variants the filters keep, of the first one on this page. Pass next_offset from the previous call to continue.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limit": {
"default": 25,
"description": "Matching variants on this page. Default 25; a value above 3,000 is clamped to 3,000, with a notice.",
"type": "number",
"minimum": 1,
"multipleOf": 1
},
"canvas_id": {
"description": "Optional canvas ID from a prior call, to reuse the same canvas. When supplied, a call at offset 0 always writes its result to the gene_variants table on that canvas, replacing (not appending to) the previous one, its columns included: the table takes this call's annotations shape — even when the result fits inline; a result with no variants removes the table. A page past offset 0 leaves the table as it was. Omit to stage on a fresh canvas only when the result is too large to inline.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$"
},
"dataset": {
"description": "gnomAD dataset, default gnomad_r4: gnomad_r4 and its subset gnomad_r4_non_ukb (GRCh38); gnomad_r3 and its subsets gnomad_r3_controls_and_biobanks, gnomad_r3_non_cancer, gnomad_r3_non_neuro, gnomad_r3_non_topmed, gnomad_r3_non_v2 (GRCh38); gnomad_r2_1 and its subsets gnomad_r2_1_controls, gnomad_r2_1_non_cancer, gnomad_r2_1_non_neuro, gnomad_r2_1_non_topmed (GRCh37); exac (GRCh37). A subset keeps only part of its parent release's samples (non_cancer leaves out cancer-study samples, non_ukb UK Biobank's) and can leave a callset unchanged: gnomad_r4_non_ukb genome counts equal gnomad_r4's, and gnomad_r2_1_non_cancer genome counts equal gnomad_r2_1's. No subset publishes joint data, and gnomAD publishes no subset coverage or constraint, so those come from the parent. Echoed in output.",
"type": "string",
"enum": [
"gnomad_r4",
"gnomad_r4_non_ukb",
"gnomad_r3",
"gnomad_r3_controls_and_biobanks",
"gnomad_r3_non_cancer",
"gnomad_r3_non_neuro",
"gnomad_r3_non_topmed",
"gnomad_r3_non_v2",
"gnomad_r2_1",
"gnomad_r2_1_controls",
"gnomad_r2_1_non_neuro",
"gnomad_r2_1_non_cancer",
"gnomad_r2_1_non_topmed",
"exac"
]
},
"reference_genome": {
"description": "Reference build. Derived from dataset when omitted: GRCh38 for gnomad_r4, gnomad_r3, and their subsets; GRCh37 for gnomad_r2_1, its subsets, and exac. If supplied it must match the dataset, or the call is rejected. Keep aligned with ensembl coordinates.",
"type": "string",
"enum": [
"GRCh38",
"GRCh37"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}