> ## 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.

# Gene Variants

> Find ClinVar variants in a human gene by NCBI Gene ID or official symbol.

Reports what a public registry, ClinVar, says about variants in a gene, for research; not medical advice. Classifications are submitters' and expert panels' interpretations. Supply exactly one NCBI Gene ID or official human gene symbol, never a person's genome, sequencing data or a VCF file. Aliases do not match: use gene\_resolve to resolve aliases first. Optionally filter by ClinVar classification properties and expert panel review; these properties can include combined classifications. By default, single\_gene excludes large deletions and duplications spanning multiple genes; include\_multi\_gene includes them. Returns up to 20 variants in search order and the total ClinVar search count. Empty classifications are null; no match returns total 0 and an empty variants list. Each vcv can be passed to variant\_clinical\_significance for details, including somatic and oncogenicity classifications. ClinVar refreshes weekly; classifications carry their last evaluated dates. NCBI places no restriction on use of ClinVar.

## Authentication

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

## Request Body

<ParamField body="gene_id" type="string">
  NCBI Gene ID, for example 672; supply exactly one of gene\_id or symbol. 1 to 12 characters.
</ParamField>

<ParamField body="symbol" type="string">
  Official human gene symbol, for example BRCA1; use gene\_resolve for aliases. 1 to 30 characters.
</ParamField>

<ParamField body="classification" type="string">
  ClinVar classification property filter; may include combined classifications. One of `pathogenic`, `likely_pathogenic`, `uncertain`, `likely_benign`, `benign`, `conflicting`.
</ParamField>

<ParamField body="expert_panel_only" type="boolean">
  Only variants reviewed by an expert panel. Defaults to `false`.
</ParamField>

<ParamField body="include_multi_gene" type="boolean">
  Include variants spanning multiple genes. Defaults to `false`.
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of variants returned. From 1 to 20. Defaults to `10`.
</ParamField>

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

## Response (200 OK)

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

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `gene_variants_find`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US National Center for Biotechnology Information (ClinVar)`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  Newest valid germline classification last\_evaluated date among the returned variants, or null when none is known.
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="integer">
  ClinVar search count, including matching records beyond the limit.
</ResponseField>

<ResponseField name="data.result.variants" type="object[]">
  Variants.
</ResponseField>

<ResponseField name="data.result.variants[].vcv" type="string">
  Vcv.
</ResponseField>

<ResponseField name="data.result.variants[].version" type="string">
  Versioned ClinVar accession.
</ResponseField>

<ResponseField name="data.result.variants[].title" type="string">
  Title.
</ResponseField>

<ResponseField name="data.result.variants[].variant_type" type="string">
  Variant type.
</ResponseField>

<ResponseField name="data.result.variants[].genes" type="object[]">
  Genes.
</ResponseField>

<ResponseField name="data.result.variants[].genes[].symbol" type="string">
  Symbol.
</ResponseField>

<ResponseField name="data.result.variants[].genes[].gene_id" type="string">
  Gene id.
</ResponseField>

<ResponseField name="data.result.variants[].protein_change" type="string">
  Protein change. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.variants[].molecular_consequences" type="string[]">
  Molecular consequences.
</ResponseField>

<ResponseField name="data.result.variants[].rsid" type="string">
  Rsid. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.variants[].germline" type="object">
  Germline. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.variants[].germline.classification" type="string">
  Classification.
</ResponseField>

<ResponseField name="data.result.variants[].germline.review_status" type="string">
  Review status.
</ResponseField>

<ResponseField name="data.result.variants[].germline.last_evaluated" type="string">
  Last evaluated date, YYYY-MM-DD, or null.
</ResponseField>

<ResponseField name="data.result.variants[].germline.conditions" type="string[]">
  Conditions.
</ResponseField>

<ResponseField name="data.result.variants[].page_url" type="string">
  Page url.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/find/gene-variants \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "gene_id": "7157",
      "classification": "pathogenic",
      "expert_panel_only": true,
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/find/gene-variants", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "gene_id": "7157",
      "classification": "pathogenic",
      "expert_panel_only": true,
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('find/gene-variants', {
    gene_id: '7157',
    classification: 'pathogenic',
    expert_panel_only: true,
    limit: 1
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "gene_variants_find",
      "result": {
        "total": 49,
        "variants": [
          {
            "vcv": "VCV001759844",
            "version": "VCV001759844.14",
            "title": "NM_000546.6(TP53):c.761T>C (p.Ile254Thr)",
            "variant_type": "single nucleotide variant",
            "genes": [
              {
                "symbol": "TP53",
                "gene_id": "7157"
              }
            ],
            "protein_change": "I215T, I122T, I254T, I95T",
            "molecular_consequences": [
              "missense variant"
            ],
            "rsid": "rs1330865474",
            "germline": {
              "classification": "Pathogenic",
              "review_status": "reviewed by expert panel",
              "last_evaluated": "2026-01-06",
              "conditions": [
                "Li-Fraumeni syndrome"
              ]
            },
            "page_url": "https://www.ncbi.nlm.nih.gov/clinvar/variation/1759844/"
          }
        ]
      },
      "evidence": {
        "source": "US National Center for Biotechnology Information (ClinVar)",
        "source_kind": "public",
        "retrieved_at": "2026-10-18T12:00:00.000Z",
        "calls": [
          {
            "retrieved_at": "2026-10-18T12:00:00.000Z"
          },
          {
            "retrieved_at": "2026-10-18T12:00:00.000Z"
          }
        ],
        "as_of": "2026-01-06"
      }
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) 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`.</Info>

## Notes

* 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.