> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/lab-reports/core-concepts.md).

# Core concepts

Session lifecycle, data model, biomarker standardization, and async processing.

## Session lifecycle

Every lab report upload creates a **session**. The session tracks the report through extraction, standardization, and delivery.

```
                          ┌──────────────────────────────┐
                          │         Upload File          │
                          │       POST /v2/reports       │
                          └──────────────┬───────────────┘
                                         │
                                         ▼
                          ┌──────────────────────────────┐
                          │        processing            │
                          │  OCR + AI extraction of      │
                          │  biomarker data from file    │
                          └──────────────┬───────────────┘
                                         │
                                         ▼
                          ┌──────────────────────────────┐
                          │        processed             │
                          │  Raw results extracted       │
                          └──────────────┬───────────────┘
                                         │
                                         ▼
                          ┌──────────────────────────────┐
                          │      standardizing           │
                          │  Fuzzy matching biomarkers,  │
                          │  mapping units to UCUM codes │
                          └──────────────┬───────────────┘
                                         │
                                         ▼
                          ┌──────────────────────────────┐
                          │      standardized            │
                          │  Results ready (queryable)   │
                          └──────────────┬───────────────┘
                                         │
                                         ▼
                          ┌──────────────────────────────┐
                          │        sending               │
                          │  Delivering to destinations  │
                          └──────────────┬───────────────┘
                                         │
                                         ▼
                          ┌──────────────────────────────┐
                          │  sent / partially_sent /     │
                          │  delivery_failed (terminal)  │
                          └──────────────────────────────┘

    A temporary problem upstream moves the session to retry_scheduled.
    Terra retries it automatically.

    A report that cannot be processed moves to:

                          ┌──────────────────────────────┐
                          │         failed               │
                          │  error recorded (terminal)   │
                          └──────────────────────────────┘
```

### Status reference

| Status            | Description                                                                              | Terminal | Results Available |
| ----------------- | ---------------------------------------------------------------------------------------- | -------- | ----------------- |
| `processing`      | Extracting biomarker data from the file                                                  | No       | No                |
| `processed`       | Extraction complete                                                                      | No       | No                |
| `standardizing`   | Matching biomarkers and mapping units to UCUM                                            | No       | No                |
| `standardized`    | Standardization complete, results queryable                                              | No       | Yes               |
| `sending`         | Delivering the report to your configured destinations                                    | No       | Yes               |
| `retry_scheduled` | Waiting to retry after a temporary problem upstream. Terra retries automatically.        | No       | Partial/No        |
| `sent`            | Delivered to all opted-in destinations                                                   | Yes      | Yes               |
| `partially_sent`  | Delivered to at least one destination, failed others                                     | Yes      | Yes               |
| `delivery_failed` | Processed, but delivery to every destination failed. Results are available over the API. | Yes      | Yes               |
| `failed`          | The report could not be processed. `error` says why.                                     | Yes      | Partial/No        |
| `cancelled`       | Processing was cancelled                                                                 | Yes      | Partial/No        |
| `deleted`         | Session has been deleted                                                                 | Yes      | No                |

{% hint style="info" %}
Status values are clean lowercase strings like `"sent"`, `"processing"`, `"failed"`, not proto-style names like `"REPORT_STATUS_SENT"`.
{% endhint %}

### When a report fails

A report that cannot be processed ends in `failed`, and the session carries an `error` object saying why:

```json
{
  "session_id": "297405620317847553",
  "current_status": "failed",
  "error": {
    "code": "unsupported_report_type",
    "message": "the file is not a lab report or a DXA scan; only those are accepted",
    "retriable": false,
    "document_class": "other_medical"
  }
}
```

It is the same object the `lab_report.failed` webhook carries. Branch on `error.code`. See [Error Codes](https://docs.tryterra.co/lab-reports/webhook-payload.md#error-codes) for every code and what to do about it. Reports that fail are not billed.

`failed` is final. Terra does not pick the report up again. Only a [reprocess](https://docs.tryterra.co/lab-reports/api-reference.md#reprocess-a-session) reopens it, and that helps only when `error.retriable` is `true`.

`delivery_failed` is not a processing failure. The report was processed and its results are available, but no destination accepted the delivery. It has no `error`. Check [`/deliveries`](https://docs.tryterra.co/lab-reports/api-reference.md#list-deliveries) for each destination's last error.

### Retries

A temporary problem upstream does not fail the report. The session moves to `retry_scheduled` and Terra retries it automatically. If the report still cannot finish after several hours, it fails with `code` `internal` and `retriable: true`, and you can reprocess it.

### One event per run

Each run of a report ends in exactly one webhook event: `lab_report.completed` or `lab_report.failed`. A cancelled run sends none. The upload is one run. Each reprocess is a new run, with its own event and `event_id`.

## Report types

One endpoint ingests two kinds of document: clinical **lab reports** and **DXA scans** (body composition and bone density). You do not declare which. Terra classifies the file on upload and reports what it decided in `report_type`.

| `report_type` | Document                         | Results are scoped by |
| ------------- | -------------------------------- | --------------------- |
| `lab`         | Clinical laboratory report       | `biomarker.specimen`  |
| `dexa`        | DXA body-composition / bone scan | `biomarker.region`    |
| `unspecified` | Not yet classified (transient)   | None                  |

Branch on `report_type` before reading results: the two carry different scoping fields, and a scan reports the same measure once per anatomical site. See [Scans (DEXA)](https://docs.tryterra.co/lab-reports/scans.md).

## Data model

The data model is a hierarchy: **Session -> Results -> Reference Ranges**. Each result is grouped into four layers: `source` (verbatim from the report), `biomarker` (normalized identity), `measurement` (one typed value), and `interpretation` (coded abnormality signal).

```
Session
├── session_id              (snowflake string)
├── upload_id               (the upload this report came from)
├── reference_id            (your external ID, omitted if not set)
├── current_status          (e.g. "sent", "processing")
├── report_type             ("lab" | "dexa" | "unspecified")
├── report_date             (YYYY-MM-DD string)
├── report_time             (HH:MM 24-hour)
├── collection_date         (YYYY-MM-DD string)
├── collection_time         (HH:MM 24-hour)
├── uploaded_at             (ISO-8601)
├── updated_at              (ISO-8601)
├── report_locale           (e.g. "ja-JP", "pt-BR")
├── lab_name                (string)
├── patient_sex             ("male", "female", or omitted)
├── patient_age_at_collection (integer, omitted if unknown)
├── report_notes            (free-text)
├── error                   (code, message, retriable, document_class; only while failed)
├── status_history[]        (status + timestamp + note entries)
├── results_count           (integer)
├── file_count              (integer)
├── input_bytes             (integer)
├── output_bytes            (integer)
│
├── panels[]                (report-level groupings, omitted if no panels)
│   ├── id                  (report-local panel id, matches biomarker.panel_id)
│   ├── name                (verbatim panel header)
│   └── key                 (normalized dedup key, may be null)
│
└── results[]
    ├── source                          (what the report literally printed)
    │   ├── name                        (exact biomarker name from the report)
    │   ├── panel                       (verbatim panel header, omitted if none)
    │   ├── value                       (value exactly as printed)
    │   ├── units                       (units as printed)
    │   ├── flag                        (raw flag text: "H", "L", "↑", etc.)
    │   ├── method                      (lab methodology, omitted if none)
    │   ├── notes                       (additional lab comments, omitted if none)
    │   ├── reference_text              (human-readable printed range)
    │   ├── collection_date             (YYYY-MM-DD, omitted if none)
    │   └── collection_time             (HH:MM 24-hour, omitted if none)
    │
    ├── biomarker                       (normalized identity)
    │   ├── key                         (canonical slug, null if no match)
    │   ├── display_name                (standardized English name)
    │   ├── loinc_code                  (LOINC code, omitted if not mapped)
    │   ├── panel_id                    (references panels[].id, omitted if none)
    │   ├── panel_key                   (normalized panel key, omitted if none)
    │   └── specimen                    ("blood", "serum", "plasma", "urine", etc.)
    │
    ├── measurement                     (one typed value: read type, then the field)
    │   ├── type                        ("numeric", "bounded", "qualitative", "text", "absent")
    │   ├── numeric                     (number, when type is "numeric")
    │   ├── bounded                     ({ operator: "lt"|"gt", value: number }, when "bounded")
    │   ├── qualitative                 ({ text: string }, when "qualitative")
    │   ├── text                        (string, when type is "text")
    │   ├── absent_reason               (string, when type is "absent")
    │   ├── units                       (units of the numeric/bounded magnitude)
    │   └── ucum_code                   (UCUM-compliant unit code)
    │
    ├── interpretation                  (coded "is this abnormal" signal)
    │   ├── flag                        ("high", "low", "normal", "critical_high", ..., null)
    │   ├── flag_raw                    (the lab's verbatim flag text)
    │   ├── source                      ("report" or "none")
    │   └── applied_range               ({ lower, upper }, the range the flag was judged against)
    │
    └── reference_ranges[]
        ├── lower               (numeric, omitted for one-sided ranges)
        ├── upper               (numeric, omitted for one-sided ranges)
        ├── type                ("normal", "low", "high", etc.)
        ├── label               (the report's own wording; type is its lossy coding)
        │
        └── context
            ├── sex                     ("male", "female", or omitted)
            ├── age_lower               (years, omitted if not specified)
            ├── age_upper               (years, omitted if no upper limit)
            ├── pregnancy_status        ("trimester_1", "trimester_2", "trimester_3")
            ├── cycle_phase             (omitted if not applicable)
            ├── gestational_week_lower  (integer, omitted if not applicable)
            ├── gestational_week_upper  (integer, omitted if not applicable)
            ├── reference_population    (e.g. "nhanes_iii", omitted if not set)
            └── modifiers[]             (string array, e.g. ["fasting", "supine"])
```

### Session object

| Field                       | Type      | Description                                                                                                              |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `session_id`                | string    | Snowflake int64 ID (as string)                                                                                           |
| `upload_id`                 | string    | The upload this report came from                                                                                         |
| `reference_id`              | object?   | Your external identifier (from upload query param)                                                                       |
| `current_status`            | string    | Current session status (e.g. `"sent"`)                                                                                   |
| `report_type`               | string    | Report type (e.g. `"lab"`)                                                                                               |
| `report_date`               | object?   | Date from the lab report (YYYY-MM-DD)                                                                                    |
| `report_time`               | object?   | Time from the lab report (HH:MM 24-hour)                                                                                 |
| `collection_date`           | object?   | Specimen collection date (YYYY-MM-DD)                                                                                    |
| `collection_time`           | object?   | Specimen collection time (HH:MM 24-hour)                                                                                 |
| `uploaded_at`               | object?   | Session creation time (ISO-8601)                                                                                         |
| `updated_at`                | object?   | Last update time (ISO-8601)                                                                                              |
| `report_locale`             | object?   | Locale of the report (e.g. `"ja-JP"`, `"pt-BR"`)                                                                         |
| `lab_name`                  | object?   | Name of the laboratory                                                                                                   |
| `patient_sex`               | string    | `"male"`, `"female"`, or omitted if unspecified                                                                          |
| `patient_age_at_collection` | integer?  | Patient age in years at specimen collection                                                                              |
| `report_notes`              | string    | Free-text notes extracted from the report                                                                                |
| `error`                     | object?   | Why the report failed. Present only while `current_status` is `failed`. See [When a Report Fails](#when-a-report-fails). |
| `status_history`            | object\[] | Array of status change entries                                                                                           |
| `results_count`             | integer   | Number of biomarker results                                                                                              |
| `file_count`                | integer   | Number of uploaded files                                                                                                 |
| `input_bytes`               | integer   | Size of uploaded file(s) in bytes                                                                                        |
| `output_bytes`              | integer   | Size of output data in bytes                                                                                             |
| `panels`                    | object\[] | Report-level panels that results reference by `panel_id` (omitted if the report has no panel grouping)                   |
| `results`                   | object\[] | Array of biomarker result objects                                                                                        |

{% hint style="info" %}
`client_id` is intentionally omitted from the API response. The API authenticates by client identity, so echoing it back is redundant.
{% endhint %}

## Biomarker standardization

When a lab report is processed, each extracted result goes through **biomarker standardization**:

1. **Fuzzy Matching**: The `source.name` from the report is matched against Terra's reference dataset of 4,100+ known biomarkers using fuzzy string matching.
2. **Key Assignment**: If a match is found, `biomarker.key` is set to a canonical slug (e.g., `"hemoglobin"`, `"glucose_fasting"`). If no confident match exists, `biomarker.key` is `null`.
3. **Display Name**: A standardized English `biomarker.display_name` is assigned from the matched biomarker.
4. **Unit Mapping**: The `source.units` (as printed on the report) are mapped to a UCUM-compliant `measurement.ucum_code` where possible.

{% hint style="warning" %}
Terra does not convert values between units. Each value and its reference range are reported in the units the lab printed, so the same biomarker can arrive in different units from different labs (for example glucose in mg/dL from one lab and mmol/L from another). Check `measurement.ucum_code` before comparing or charting values across reports.
{% endhint %}

{% hint style="warning" %}
`biomarker.key` can be `null` for uncommon or lab-specific tests. Always handle this case in your code: use `source.name` as a fallback for display.
{% endhint %}

Entries are **pooled by report type**: a scan's results are matched only against scan entries and a lab report's only against lab entries, so a body-composition measure can never be mistaken for a blood analyte. A handful of entries (height, weight, BMI) sit in both pools because both kinds of report print them.

### Site-scoped results

On a lab report, `biomarker.key` identifies a result: a biomarker appears once.

On a **scan** it does not. The same measure is reported once per place on the body: a total-body scan carries fat mass for the head, each limb, the trunk, android, gynoid and the whole body, all under `biomarker.key` = `fat_mass`. What separates them is `biomarker.region`.

> The identity of a scan result is the pair **(`biomarker.key`, `biomarker.region`)**.

`biomarker.region` is the canonical key from a closed vocabulary. Use it for storage and joins. `source.region_name` is the site as the report printed it. Use it for display.

This matters for storage: keying on `biomarker.key` alone keeps one row per measure and silently discards every other site. See [Scans (DEXA)](https://docs.tryterra.co/lab-reports/scans.md) for the vocabulary and [Best practices](https://docs.tryterra.co/lab-reports/best-practices.md) for the storage pattern.

See [Biomarker reference](https://docs.tryterra.co/lab-reports/biomarker-reference.md) for details on the matching system and a list of common biomarkers.

## UCUM unit codes

Terra maps lab report units to [UCUM (Unified Code for Units of Measure)](https://ucum.org/) codes wherever possible. This gives you a machine-readable, internationally standardized representation of the unit.

| Report Prints | `ucum_code` |
| ------------- | ----------- |
| g/dL          | `g/dL`      |
| mg/dL         | `mg/dL`     |
| mmol/L        | `mmol/L`    |
| 10^9/L        | `10*9/L`    |
| mIU/L         | `m[IU]/L`   |
| pg/mL         | `pg/mL`     |

When UCUM mapping is not possible (e.g., proprietary lab units), `measurement.ucum_code` is omitted and `source.units` still reflects what the report printed.

## Measurement types

Every result carries a single `measurement` object. Read `measurement.type`, then read the matching field:

| `measurement.type` | Read this field             | Description                                                  | Example                       |
| ------------------ | --------------------------- | ------------------------------------------------------------ | ----------------------------- |
| `numeric`          | `measurement.numeric`       | A numeric measurement with optional units                    | Hemoglobin: 14.2 g/dL         |
| `bounded`          | `measurement.bounded`       | A one-sided bound: `{ operator: "lt"\|"gt", value: number }` | PSA: `<0.04`                  |
| `qualitative`      | `measurement.qualitative`   | A categorical outcome: `{ text: string }`                    | HIV screen: Non-Reactive      |
| `text`             | `measurement.text`          | Free-text observation                                        | Morphology: Normal appearance |
| `absent`           | `measurement.absent_reason` | No value could be extracted                                  | Value not reported            |

`measurement.units` and `measurement.ucum_code` describe the magnitude for `numeric`/`bounded` results. For a report showing `<0.01`, `measurement.type` is `"bounded"` and `measurement.bounded` is `{ "operator": "lt", "value": 0.01 }`; for `>5.0` it is `{ "operator": "gt", "value": 5.0 }`.

## Interpretation flag

Each result's `interpretation` object carries the coded per-result abnormality signal. `interpretation.flag` is a **normalized** code (or `null` when there is no signal), while `interpretation.flag_raw` preserves the lab's verbatim flag text and `source.flag` carries that raw text on the source layer. `interpretation.source` is `"report"` when the flag was normalized from the printed flag, or `"none"` when there is no signal.

| `interpretation.flag` | Meaning                        | Common raw flag(s) |
| --------------------- | ------------------------------ | ------------------ |
| `normal`              | Not flagged                    | `"N"`              |
| `high`                | Above range                    | `"H"`, `"↑"`       |
| `low`                 | Below range                    | `"L"`, `"↓"`       |
| `critical_high`       | Critically high                | `"HH"`             |
| `critical_low`        | Critically low                 | `"LL"`             |
| `borderline_high`     | Borderline high                |                    |
| `borderline_low`      | Borderline low                 |                    |
| `abnormal`            | Flagged, direction unspecified | `"A"`, `"C"`       |

`interpretation.flag` is `null` when the lab did not flag that result. The raw lab string it was derived from is preserved in `interpretation.flag_raw` and `source.flag`. Those are the lab's own text (e.g. `"H"`, `"↑"`, `"Négatif"`), **not** an enum.

## Async processing model

Lab report processing is **fully asynchronous**:

1. **Upload**: `POST /v2/reports` returns `202 Accepted` immediately with an `upload_id`. The report's `session_id` arrives in the webhook event, or list it with `GET /v2/reports?upload_id=`.
2. **Processing**: Extraction and standardization happen in the background. This typically takes 3 to 5 minutes and can take longer under heavy load. Design your app so users can leave and come back to their results.
3. **Delivery**: Once complete, the full session payload is delivered to your webhook. You can also poll `GET /v2/reports/{session_id}` at any time.

{% hint style="info" %}
Results become available on the GET endpoint as soon as the session reaches `standardized`, even before webhook delivery.
{% endhint %}

## Delivery destinations

Lab reports are not webhook-only. A completed report can be delivered to **any** destination type you have configured: webhooks, cloud storage (S3, GCS, Azure Blob), message queues (SQS, Kafka), and databases (MongoDB, Firestore, SQL, Supabase).

### Opting a destination in

Delivery is **opt-in per destination**. A destination receives lab reports only if its event-type allow-list explicitly includes lab reports. Destinations that don't opt in are simply skipped (they aren't marked failed, and skipping one never affects the others).

Set the allow-list with the `destination_event_types` field when you create or update a destination, and include `"lab_report"` in it:

```json
{
  "destination_event_types": ["lab_report"]
}
```

A destination's `destination_event_types` may list more than one event type. Add `"lab_report"` to an existing destination's array to start sending lab reports there alongside whatever it already receives.

### Per-destination outcomes

Each destination's delivery is tracked **independently**. A report fanned out to several destinations records a separate outcome (`pending` → `delivered`/`failed`) for each one, so a failure to one destination never hides that the report reached the others, and never fails the report as a whole.

When some destinations succeed and others fail, the session ends in the `partially_sent` status (terminal). When every destination fails, it ends in `delivery_failed` (terminal), and the results are still available over the API. Retrieve the per-destination state, including the `destination_type`, `status`, `attempt_count`, and any `last_error`, from the [`/deliveries` sub-resource](https://docs.tryterra.co/lab-reports/api-reference.md#list-deliveries).

### How each type receives the report

* **Storage destinations** (S3, GCS, Azure Blob, Supabase) and **document databases** (MongoDB, Firestore) receive the **full report body**.
* **Row and message destinations** (SQL, SQS, Kafka) receive a **link to the report** (a time-limited URL) rather than the full body. Fetch the report from that link, or from `GET /v2/reports/{session_id}`.

## Timestamps and serialization

All timestamps in responses are **ISO-8601 format** (e.g., `"2026-03-28T14:22:10Z"`).

All enum values are serialized as **clean lowercase strings**, not proto-style names or integer codes:

* Status: `"sent"` (not `"REPORT_STATUS_SENT"` or `6`)
* Measurement type: `"numeric"` (not `"LAB_REPORT_RESULT_TYPE_NUMERIC"`)
* Specimen: `"blood"` (not `"LAB_REPORT_SPECIMEN_TYPE_BLOOD"`)
* Reference range type: `"normal"` (not `"LAB_REPORT_RANGE_CLASSIFICATION_NORMAL"`); the report's own wording is in `label`
* Interpretation flag: `"high"` (not `"LAB_REPORT_FLAG_HIGH"`)
* Biological sex: `"male"` (not `"BIOLOGICAL_SEX_MALE"`)

The raw lab flag on `source.flag` (and mirrored in `interpretation.flag_raw`) is the lab's own string (e.g., `"H"`, `"L"`), not an enum. The normalized `interpretation.flag` **is** an enum.

{% hint style="warning" %}
**Open enums:** All enum fields (`current_status`, `report_type`, `measurement.type`, `biomarker.specimen`, `reference_ranges[].type`, `interpretation.flag`, `patient_sex`, `error.code`, `error.document_class`) may receive **new values** in future updates without a major version change. Your code should handle unknown enum values gracefully, for example by treating them as a default/unknown category rather than throwing an error.
{% endhint %}

Optional fields that are unset are **omitted** from the JSON response rather than appearing as `null`.

## Session IDs

Session IDs are **snowflake int64** values. In JSON they are serialized as **strings** to prevent precision loss in languages like JavaScript where `Number` cannot represent the full int64 range.

```json
{
  "session_id": "297405620317847552"
}
```

Always store and compare session IDs as strings.

## Retention and deletion

Terra keeps a report until you delete it or close your account. Delete one with [`DELETE /v2/reports/{session_id}`](https://docs.tryterra.co/lab-reports/api-reference.md#delete-a-session). It disappears from the API at once, and its files and results are erased from active systems within 30 days, with a target of 24 hours. Copies already delivered to your destinations are yours to delete.
