> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variant Frequency

> Look up aggregate allele counts and frequencies for a human variant on GRCh38.

Reports aggregate allele counts and frequencies from the Genome Aggregation Database (gnomAD), Broad Institute, showing what a public reference population contains, by genetic ancestry group. For research; not medical advice. An rsID matching several variants needs the variant\_id.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**variant\_id** `string`

gnomAD variant ID on GRCh38, for example 1-55051215-G-GA; supply only variant\_id or rsid.

**rsid** `string`

dbSNP identifier, for example rs527413419; supply only rsid or variant\_id.

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `variant_frequency`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `Genome Aggregation Database (gnomAD), Broad Institute`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

No date is supplied by the source; data refresh per versioned release.

## Result

Nested under `data.result`.

**data.result.found** `boolean`

Found.

**data.result.note** `string | null`

Note. `null` when the source gives no value.

**data.result.variant\_id** `string | null`

Variant id. `null` when the source gives no value.

**data.result.rsids** `string[]`

Rsids.

**data.result.reference\_genome** `string | null`

Reference genome. `null` when the source gives no value.

**data.result.chrom** `string | null`

Chrom. `null` when the source gives no value.

**data.result.pos** `integer | null`

Pos. `null` when the source gives no value.

**data.result.ref** `string | null`

Ref. `null` when the source gives no value.

**data.result.alt** `string | null`

Alt. `null` when the source gives no value.

**data.result.exome** `object | null`

Exome. `null` when the source gives no value.

**data.result.exome.allele\_count** `integer`

Allele count.

**data.result.exome.allele\_number** `integer`

Allele number.

**data.result.exome.allele\_frequency** `number | null`

Allele frequency. `null` when the source gives no value.

**data.result.exome.homozygotes** `integer`

Homozygotes.

**data.result.exome.hemizygotes** `integer`

Hemizygotes.

**data.result.exome.filters** `string[]`

Empty means it passed quality filters.

**data.result.exome.populations** `object[]`

Populations.

**data.result.exome.populations\[].group** `string`

Group.

**data.result.exome.populations\[].allele\_count** `integer`

Allele count.

**data.result.exome.populations\[].allele\_number** `integer`

Allele number.

**data.result.exome.populations\[].allele\_frequency** `number | null`

Allele frequency. `null` when the source gives no value.

**data.result.exome.populations\[].homozygotes** `integer`

Homozygotes.

**data.result.genome** `object | null`

Genome. `null` when the source gives no value.

**data.result.genome.allele\_count** `integer`

Allele count.

**data.result.genome.allele\_number** `integer`

Allele number.

**data.result.genome.allele\_frequency** `number | null`

Allele frequency. `null` when the source gives no value.

**data.result.genome.homozygotes** `integer`

Homozygotes.

**data.result.genome.hemizygotes** `integer`

Hemizygotes.

**data.result.genome.filters** `string[]`

Empty means it passed quality filters.

**data.result.genome.populations** `object[]`

Populations.

**data.result.genome.populations\[].group** `string`

Group.

**data.result.genome.populations\[].allele\_count** `integer`

Allele count.

**data.result.genome.populations\[].allele\_number** `integer`

Allele number.

**data.result.genome.populations\[].allele\_frequency** `number | null`

Allele frequency. `null` when the source gives no value.

**data.result.genome.populations\[].homozygotes** `integer`

Homozygotes.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/variant-frequency \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "variant_id": "1-55051215-G-GA"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/variant-frequency", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "variant_id": "1-55051215-G-GA"
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/variant-frequency', {
  variant_id: '1-55051215-G-GA'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "variant_frequency",
    "result": {
      "found": true,
      "note": null,
      "variant_id": "1-55051215-G-GA",
      "rsids": [
        "rs527413419"
      ],
      "reference_genome": "GRCh38",
      "chrom": "1",
      "pos": 55051215,
      "ref": "G",
      "alt": "GA",
      "exome": {
        "allele_count": 192,
        "allele_number": 303936,
        "allele_frequency": 0.0006317119393556538,
        "homozygotes": 2,
        "hemizygotes": 0,
        "filters": [],
        "populations": [
          {
            "group": "remaining",
            "allele_count": 16,
            "allele_number": 14228,
            "allele_frequency": 0.001124543154343548,
            "homozygotes": 0
          },
          {
            "group": "amr",
            "allele_count": 19,
            "allele_number": 27270,
            "allele_frequency": 0.0006967363403006967,
            "homozygotes": 0
          },
          {
            "group": "fin",
            "allele_count": 0,
            "allele_number": 12364,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "mid",
            "allele_count": 5,
            "allele_number": 2782,
            "allele_frequency": 0.0017972681524083393,
            "homozygotes": 0
          },
          {
            "group": "nfe",
            "allele_count": 7,
            "allele_number": 158924,
            "allele_frequency": 0.00004404621076741084,
            "homozygotes": 0
          },
          {
            "group": "sas",
            "allele_count": 2,
            "allele_number": 59744,
            "allele_frequency": 0.000033476164970540974,
            "homozygotes": 0
          },
          {
            "group": "asj",
            "allele_count": 0,
            "allele_number": 10788,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "eas",
            "allele_count": 0,
            "allele_number": 9210,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "afr",
            "allele_count": 143,
            "allele_number": 8626,
            "allele_frequency": 0.016577788082541154,
            "homozygotes": 2
          }
        ]
      },
      "genome": {
        "allele_count": 727,
        "allele_number": 152324,
        "allele_frequency": 0.004772721304587589,
        "homozygotes": 9,
        "hemizygotes": 0,
        "filters": [],
        "populations": [
          {
            "group": "remaining",
            "allele_count": 10,
            "allele_number": 2114,
            "allele_frequency": 0.004730368968779565,
            "homozygotes": 0
          },
          {
            "group": "amr",
            "allele_count": 27,
            "allele_number": 15296,
            "allele_frequency": 0.0017651673640167365,
            "homozygotes": 0
          },
          {
            "group": "fin",
            "allele_count": 0,
            "allele_number": 10630,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "ami",
            "allele_count": 0,
            "allele_number": 912,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "eas",
            "allele_count": 0,
            "allele_number": 5176,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "mid",
            "allele_count": 0,
            "allele_number": 294,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "sas",
            "allele_count": 1,
            "allele_number": 4834,
            "allele_frequency": 0.0002068680182043856,
            "homozygotes": 0
          },
          {
            "group": "asj",
            "allele_count": 0,
            "allele_number": 3472,
            "allele_frequency": 0,
            "homozygotes": 0
          },
          {
            "group": "afr",
            "allele_count": 683,
            "allele_number": 41568,
            "allele_frequency": 0.016430908391070052,
            "homozygotes": 9
          },
          {
            "group": "nfe",
            "allele_count": 6,
            "allele_number": 68028,
            "allele_frequency": 0.00008819897689186806,
            "homozygotes": 0
          }
        ]
      }
    },
    "evidence": {
      "source": "Genome Aggregation Database (gnomAD), Broad Institute",
      "source_kind": "public",
      "retrieved_at": "2026-10-25T00:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-25T00:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Supply one variant identifier, never a person’s genome, sequencing data or a VCF file.
* Uses gnomAD v4 (GRCh38), exomes and genomes. Data refresh per versioned release; no observation date is supplied.
* Primary exome and genome data are CC0 1.0. Never try to reidentify participants.
* Only ancestry groups are returned; sex splits, reference-panel subsets and other annotations are excluded.
* An absent data type is null. Allele frequency is allele count divided by allele number, or null when the denominator is zero.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.