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

# Get Lab Results

> Retrieve clinical and genetic lab results for an appointment

Retrieve clinical and genetic lab results for an appointment, along with document references for lab report PDFs.

Every biomarker ordered for the appointment appears in the response, so you can track the whole order rather than only what has come back. Read `status` on each result before using its `value`:

* Tests still outstanding appear with status `planned` while the appointment is `in_progress`.
* Results the lab delivered but that must **not** be used clinically appear with status `fault` or `undeliverable`, and carry a `status_reason` explaining why. A `fault` result still has its `value` populated — that value is wrong. Never present it as a finding.

Use [Download Document](/api/documents/download-document) to download lab report PDFs referenced in the `documents` array.

## Request

### Path parameters

<ParamField path="id" type="string" required>
  Unique identifier (UUID) of the appointment to retrieve results for.
</ParamField>

## Response

On success, the API returns `200 OK` with the results object.

<ResponseField name="status" type="string" required>
  Overall results status. One of `in_progress` (some submissions still processing) or `completed`
  (all done).
</ResponseField>

<ResponseField name="clinical_results" type="object[]" required>
  Array of clinical biomarker results.

  <Expandable title="clinical result object">
    <ResponseField name="status" type="string" required>
      Result status. One of:

      * `planned` — ordered, not returned by the lab yet. `value` is `null`.
      * `received` — delivered by the lab.
      * `corrected` — delivered, then revised by a human. `value` is the corrected value.
      * `fault` — delivered but confirmed wrong; **do not use clinically**. `value` is populated with the wrong figure. See `status_reason`.
      * `undeliverable` — the lab could not produce a value. `value` is `null`. See `status_reason`.
    </ResponseField>

    <ResponseField name="status_reason" type="string" required>
      Why the result is unusable. Populated for `fault` and `undeliverable`, `null` for every other status.

      Distinct from `comment`, which is the lab's own note on the report — `comment` is empty on most faulted results, so treat `status_reason` as the authoritative explanation.
    </ResponseField>

    <ResponseField name="biomarker_id" type="integer" required>
      Biomarker identifier.
    </ResponseField>

    <ResponseField name="biomarker_name" type="string" required>
      Biomarker display name.
    </ResponseField>

    <ResponseField name="category" type="string">
      Biomarker category (e.g., Hormones, Vitamins). May be `null`.
    </ResponseField>

    <ResponseField name="value" type="number">
      Effective result value (corrected if available, otherwise raw). May be `null`.
    </ResponseField>

    <ResponseField name="value_operator" type="string">
      Comparison operator for the value: `eq` (equals), `lt` (less than), or `gt` (greater than). May be `null`.
    </ResponseField>

    <ResponseField name="unit_id" type="integer">
      Measurement unit identifier. May be `null`.
    </ResponseField>

    <ResponseField name="unit" type="string">
      Measurement unit display name. May be `null`.
    </ResponseField>

    <ResponseField name="reference_range_lab" type="object">
      Reference ranges reported by the lab for **this** result, converted to the same unit as `value`. `null` when the lab reported no range.

      A bound the lab left open stays `null`, so a one-sided interval populates only its own end — an upper threshold arrives as `normal_min: null, normal_max: 50`, a lower one as `normal_min: 55, normal_max: null`. Do not read a `null` bound as zero or unbounded-by-default; read it as "the lab set no limit on that side".

      Each result carries the range it was measured against, so a patient whose results span several draws or several labs gets the correct interval per result rather than the most recent one.

      <Expandable title="reference range">
        <ResponseField name="normal_min" type="number">Lower bound of normal range. May be `null`.</ResponseField>
        <ResponseField name="normal_max" type="number">Upper bound of normal range. May be `null`.</ResponseField>
        <ResponseField name="optimal_min" type="number">Lower bound of optimal range. May be `null`.</ResponseField>
        <ResponseField name="optimal_max" type="number">Upper bound of optimal range. May be `null`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="reference_range_aniva" type="object">
      Aniva-curated reference ranges adjusted for age, sex, and pregnancy status. May be `null`.

      <Expandable title="reference range">
        <ResponseField name="normal_min" type="number">Lower bound of normal range. May be `null`.</ResponseField>
        <ResponseField name="normal_max" type="number">Upper bound of normal range. May be `null`.</ResponseField>
        <ResponseField name="optimal_min" type="number">Lower bound of optimal range. May be `null`.</ResponseField>
        <ResponseField name="optimal_max" type="number">Upper bound of optimal range. May be `null`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tested_at" type="string">
      Date the test was performed in `YYYY-MM-DD` format. May be `null`.
    </ResponseField>

    <ResponseField name="comment" type="string">
      Optional comment on the result. May be `null`.
    </ResponseField>

    <ResponseField name="lab_reported" type="object">
      The performing lab's own report line, verbatim — for reading this payload against the lab's PDF. May be `null` when we hold no raw record for the result.

      Every other field on a result is normalized: `value` and `unit` are converted to the biomarker's default unit, and `biomarker_name` is our name for the analyte, not the lab's. The fields below are not. Treat them as the as-printed reference and the canonical fields as the consistency cross-check.

      Numbers here are the lab's own bounds on the lab's own scale — `reference_range_min` and `reference_range_max` are **not** unit-converted and will differ from `reference_range_lab` wherever the two scales differ. A bound the lab left open stays `null`; nothing is inferred or defaulted.

      <Expandable title="lab reported">
        <ResponseField name="name" type="string">Analyte name as printed by the lab. May be `null`.</ResponseField>
        <ResponseField name="code" type="string">The lab's own analyte code. May be `null`.</ResponseField>
        <ResponseField name="category" type="string">Report section heading, e.g. `Klinische Chemie`. May be `null`.</ResponseField>
        <ResponseField name="value" type="string">Value as printed. A string, so non-numeric results survive intact (`<0.04`, `negativ`, `1:100`). May be `null`.</ResponseField>
        <ResponseField name="unit" type="string">Unit as printed, e.g. `U/l`. May be `null`.</ResponseField>
        <ResponseField name="reference_range" type="string">Reference interval as printed, including one-sided thresholds: `40 - 129`, `< 50`, `> 55`. May be `null`.</ResponseField>
        <ResponseField name="reference_range_min" type="number">The lab's lower bound, unconverted. `null` for an interval the lab left open below.</ResponseField>
        <ResponseField name="reference_range_max" type="number">The lab's upper bound, unconverted. `null` for an interval the lab left open above.</ResponseField>
        <ResponseField name="flag" type="string">The lab's abnormality flag for this line: `normal`, `high`, `low`, `critical_high`, `critical_low`, `abnormal`. A code we do not recognize passes through as the lab sent it. May be `null`.</ResponseField>
        <ResponseField name="result_status" type="string">The lab's result status: `final`, `preliminary`, `correction`, `incomplete`, `partial`, `deleted`, `cannot_be_obtained`. A `preliminary` value can still be revised — re-poll before treating it as settled. May be `null`.</ResponseField>
        <ResponseField name="comment" type="string">The lab's own note on this line. Column padding is collapsed; wording is untouched. May be `null`.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="genetic_results" type="object[]" required>
  Array of genetic biomarker results.

  <Expandable title="genetic result object">
    <ResponseField name="status" type="string" required>
      Result status. One of:

      * `planned` — ordered, not returned by the lab yet.
      * `received` — delivered by the lab.
      * `fault` — delivered but confirmed wrong; **do not use clinically**. See `status_reason`.
      * `undeliverable` — the lab could not produce a genotype. See `status_reason`.
    </ResponseField>

    <ResponseField name="status_reason" type="string" required>
      Why the result is unusable. Populated for `fault` and `undeliverable`, `null` for every other status.
    </ResponseField>

    <ResponseField name="biomarker_id" type="integer" required>
      Biomarker (gene) identifier.
    </ResponseField>

    <ResponseField name="gene" type="string" required>
      Gene symbol (e.g., APOE, MTHFR).
    </ResponseField>

    <ResponseField name="genotype" type="string">
      Genotype display (e.g., E3/E4). May be `null`.
    </ResponseField>

    <ResponseField name="clinical_significance" type="string">
      Overall clinical significance. One of `pathogenic`, `likely_pathogenic`, `uncertain`, `likely_benign`, `benign`, `high_risk`, `moderate_risk`, `low_risk`, `protective`, `drug_response`, `poor_metabolizer`, or `rapid_metabolizer`. May be `null`.
    </ResponseField>

    <ResponseField name="risk_description" type="string">
      Risk description for this genotype. May be `null`.
    </ResponseField>

    <ResponseField name="tested_at" type="string">
      Date the test was performed in `YYYY-MM-DD` format. May be `null`.
    </ResponseField>

    <ResponseField name="comment" type="string">
      Optional comment on the result. May be `null`.
    </ResponseField>

    <ResponseField name="variants" type="object[]" required>
      Detected genetic variants.

      <Expandable title="variant object">
        <ResponseField name="name" type="string" required>Variant common name (e.g., APOE E4).</ResponseField>
        <ResponseField name="clinical_significance" type="string">Variant-level clinical significance. May be `null`.</ResponseField>
        <ResponseField name="description" type="string">Variant description. May be `null`.</ResponseField>
        <ResponseField name="hgvs_c" type="string">HGVS coding DNA notation. May be `null`.</ResponseField>
        <ResponseField name="hgvs_p" type="string">HGVS protein notation. May be `null`.</ResponseField>

        <ResponseField name="conditions" type="object[]" required>
          Associated conditions.

          <Expandable title="condition object">
            <ResponseField name="condition" type="string" required>Condition/disease name.</ResponseField>
            <ResponseField name="association_description" type="string">Description of the variant-condition association. May be `null`.</ResponseField>
            <ResponseField name="badge" type="string">Short badge text for display. May be `null`.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="snvs" type="object[]" required>
          Single nucleotide variants defining this variant.

          <Expandable title="SNV object">
            <ResponseField name="rs_id" type="string" required>dbSNP identifier (e.g., rs429358).</ResponseField>
            <ResponseField name="allele" type="string" required>Variant allele (`A`, `C`, `G`, `T`, `del`, `ins`, or `undetermined`).</ResponseField>
            <ResponseField name="reference_allele" type="string" required>Population reference allele.</ResponseField>
            <ResponseField name="hgvs_c" type="string">HGVS coding DNA notation. May be `null`.</ResponseField>
            <ResponseField name="hgvs_p" type="string">HGVS protein notation. May be `null`.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="documents" type="object[]" required>
  Lab report documents. Use `GET /api/v1/documents/{id}` to download each file.

  <Expandable title="document object">
    <ResponseField name="id" type="string" required>File identifier (UUID). Pass to [Download Document](/api/documents/download-document) to retrieve the file.</ResponseField>
    <ResponseField name="file_name" type="string" required>Original file name.</ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Description                                                                                                        |
| ------ | ------------------------------------------------------------------------------------------------------------------ |
| `400`  | Invalid ID format — the provided value is not a valid UUID.                                                        |
| `403`  | Forbidden — your API key does not have access to this operation or the appointment is outside your access context. |
| `404`  | Appointment not found.                                                                                             |
| `500`  | Internal server error.                                                                                             |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a/results \
    --header 'x-api-key: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "in_progress",
    "clinical_results": [
      {
        "status": "received",
        "status_reason": null,
        "biomarker_id": 104,
        "biomarker_name": "Vitamin D",
        "category": "Vitamins",
        "value": 38.5,
        "value_operator": "eq",
        "unit_id": 1,
        "unit": "ng/mL",
        "reference_range_lab": {
          "normal_min": 30,
          "normal_max": 100,
          "optimal_min": null,
          "optimal_max": null
        },
        "reference_range_aniva": {
          "normal_min": 30,
          "normal_max": 80,
          "optimal_min": 40,
          "optimal_max": 60
        },
        "tested_at": "2026-04-05",
        "comment": null,
        "lab_reported": {
          "name": "Vitamin D (25-OH)",
          "code": "vitd",
          "category": "Endokrinologie",
          "value": "38.5",
          "unit": "ng/ml",
          "reference_range": "30 - 100",
          "reference_range_min": 30,
          "reference_range_max": 100,
          "flag": "normal",
          "result_status": "final",
          "comment": null
        }
      },
      {
        "status": "received",
        "status_reason": null,
        "biomarker_id": 93,
        "biomarker_name": "Alanine Aminotransferase (ALT)",
        "category": "Liver",
        "value": 0.33,
        "value_operator": "eq",
        "unit_id": 63,
        "unit": "µkat/L",
        "reference_range_lab": {
          "normal_min": null,
          "normal_max": 0.82,
          "optimal_min": null,
          "optimal_max": null
        },
        "reference_range_aniva": null,
        "tested_at": "2026-04-05",
        "comment": null,
        "lab_reported": {
          "name": "GPT (ALT) (S, U/l)",
          "code": "gpt",
          "category": "Klinische Chemie",
          "value": "20",
          "unit": "U/l",
          "reference_range": "< 50",
          "reference_range_min": null,
          "reference_range_max": 49,
          "flag": "normal",
          "result_status": "final",
          "comment": null
        }
      },
      {
        "status": "fault",
        "status_reason": "Sample tube contaminated with manganese — implausibly high value; the lab cancelled the request and asked for a lithium-heparin tube.",
        "biomarker_id": 326,
        "biomarker_name": "Manganese, whole blood mixture",
        "category": "Micronutrients",
        "value": 114,
        "value_operator": "eq",
        "unit_id": 24,
        "unit": "µg/L",
        "reference_range_lab": {
          "normal_min": 6,
          "normal_max": 11,
          "optimal_min": null,
          "optimal_max": null
        },
        "reference_range_aniva": null,
        "tested_at": "2026-04-05",
        "comment": null,
        "lab_reported": {
          "name": "Mangan (Vollblut, µg/l)",
          "code": "mn",
          "category": "Spurenelemente",
          "value": "114",
          "unit": "µg/l",
          "reference_range": "6 - 11",
          "reference_range_min": 6,
          "reference_range_max": 11,
          "flag": "critical_high",
          "result_status": "final",
          "comment": null
        }
      },
      {
        "status": "planned",
        "status_reason": null,
        "biomarker_id": 79,
        "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
        "category": "Hormones",
        "value": null,
        "value_operator": null,
        "unit_id": null,
        "unit": null,
        "reference_range_lab": null,
        "reference_range_aniva": null,
        "tested_at": null,
        "comment": null,
        "lab_reported": null
      }
    ],
    "genetic_results": [
      {
        "status": "received",
        "status_reason": null,
        "biomarker_id": 348,
        "gene": "APOE",
        "genotype": "E3/E4",
        "clinical_significance": "moderate_risk",
        "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
        "tested_at": "2026-04-05",
        "comment": null,
        "variants": [
          {
            "name": "APOE E4",
            "clinical_significance": "moderate_risk",
            "description": "The E4 allele is associated with increased Alzheimer's risk.",
            "hgvs_c": "c.388T>C",
            "hgvs_p": "p.Cys130Arg",
            "conditions": [
              {
                "condition": "Alzheimer's disease",
                "association_description": "Increased risk with one E4 allele",
                "badge": "Moderate Risk"
              }
            ],
            "snvs": [
              {
                "rs_id": "rs429358",
                "allele": "C",
                "reference_allele": "T",
                "hgvs_c": "c.388T>C",
                "hgvs_p": "p.Cys130Arg"
              }
            ]
          }
        ]
      }
    ],
    "documents": [
      {
        "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
        "file_name": "lab-report-2026-04-05.pdf"
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Appointment not found"
  }
  ```
</ResponseExample>