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

# Lab Results Agent

> Analyze lab results with patient context for clinical interpretation

The Lab Results Agent is optimized for interpreting laboratory test results. Unlike the EHR Agent which analyzes comprehensive health data, the Lab Results Agent accepts lab tests directly and focuses on clinical interpretation. Analysis is backed by peer-reviewed medical literature and curated clinical guidelines from leading medical societies.

## When to Use

<CardGroup cols={2}>
  <Card title="Lab Results Agent" icon="flask-vial">
    **Best for:**

    * Lab result interpretation
    * Post-visit lab review
    * Routine monitoring analysis
    * Direct lab-to-patient communication

    **Input:** Lab results + optional patient context
  </Card>

  <Card title="EHR Agent" icon="file-medical">
    **Best for:**

    * Comprehensive health analysis
    * Multi-system assessment
    * Complex cases with imaging/genetics
    * Pre-visit preparation

    **Input:** Full EHR data bundle
  </Card>
</CardGroup>

## Endpoint

```
POST https://api.heliosai.health/api/v1/lab-results
```

## Request Format

```json theme={null}
{
  "webhookUrl": "https://your-server.com/webhook/helios",
  "labResults": [
    {
      "name": "Creatinine",
      "value": "1.8 mg/dL",
      "flag": "High",
      "referenceRange": "0.7-1.3 mg/dL",
      "date": "2025-01-15",
      "category": "Renal"
    },
    {
      "name": "eGFR",
      "value": "38 mL/min/1.73m2",
      "flag": "Low",
      "referenceRange": ">60 mL/min/1.73m2",
      "date": "2025-01-15",
      "category": "Renal"
    }
  ],
  "patientContext": {
    "age": "58",
    "gender": "male",
    "conditions": [
      { "name": "Type 2 Diabetes Mellitus", "status": "active" },
      { "name": "Chronic Kidney Disease, Stage 3b", "status": "active" }
    ],
    "medications": [
      { "name": "Metformin", "dosage": "1000mg", "frequency": "twice daily" },
      { "name": "Lisinopril", "dosage": "20mg", "frequency": "once daily" }
    ]
  }
}
```

### Required Fields

| Field        | Type   | Description                                  |
| ------------ | ------ | -------------------------------------------- |
| `webhookUrl` | string | HTTPS URL to receive results                 |
| `labResults` | array  | Lab test results to analyze (min 1, max 200) |

### Lab Result Fields

| Field            | Type   | Required | Description                                                     |
| ---------------- | ------ | -------- | --------------------------------------------------------------- |
| `name`           | string | Yes      | Lab test name (e.g., "Creatinine", "Hemoglobin A1c")            |
| `value`          | string | Yes      | Result value, may include unit (e.g., "1.8 mg/dL" or "7.2%")    |
| `flag`           | string | No       | Abnormality flag: `High`, `Low`, `Normal`, `Critical`           |
| `referenceRange` | string | No       | Normal reference range (e.g., "0.7-1.3 mg/dL")                  |
| `date`           | string | No       | Date of test (ISO 8601 or YYYY-MM-DD). **Recommended**          |
| `unit`           | string | No       | Unit of measurement (if not in value)                           |
| `category`       | string | No       | Lab category for database matching (e.g., "Renal", "Metabolic") |
| `notes`          | string | No       | Additional context                                              |

<Warning>
  **Dates are strongly recommended.** When provided, labs are sorted by date (most recent first) before the 200-lab limit is applied. Without dates, labs are processed in the order received.
</Warning>

### Patient Context (Optional)

Providing patient context significantly improves interpretation quality:

| Field           | Type   | Max | Description                      |
| --------------- | ------ | --- | -------------------------------- |
| `name`          | string | -   | Patient name or identifier       |
| `age`           | string | -   | Patient age                      |
| `gender`        | string | -   | Patient gender                   |
| `conditions`    | array  | 100 | Medical conditions/diagnoses     |
| `medications`   | array  | 30  | Current medications              |
| `allergies`     | array  | 20  | Known allergies                  |
| `familyHistory` | array  | 20  | Family medical history           |
| `vitalSigns`    | array  | -   | Recent vital signs               |
| `socialHistory` | string | -   | Smoking, alcohol, diet, exercise |
| `clinicalNotes` | string | -   | Free-text clinical notes         |

## Error Responses

### 400 Bad Request — Validation Error

```json theme={null}
{
  "error": "Validation error",
  "details": [
    { "path": "labResults", "message": "Required" }
  ]
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

### 429 Too Many Requests

Returned when your company has reached its concurrent request limit. Includes a `Retry-After` header indicating how long to wait (in seconds).

```json theme={null}
{
  "error": "Too many concurrent requests",
  "message": "You have 7 active lab-results requests. Maximum is 7.",
  "activeCount": 7,
  "limit": 7
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}
```

## Response Format

### Immediate Response (200 OK)

```json theme={null}
{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "message": "Request accepted. Results will be delivered to your webhook."
}
```

### Response Headers

| Header                   | Description                          | Example |
| ------------------------ | ------------------------------------ | ------- |
| `X-Concurrent-Limit`     | Maximum concurrent requests          | `7`     |
| `X-Concurrent-Active`    | Active requests (including this one) | `2`     |
| `X-Concurrent-Remaining` | Available slots                      | `5`     |

### Webhook Delivery

Results are delivered to your webhook URL in 3-6 minutes:

```json theme={null}
{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "agent": "lab-results",
  "timestamp": "2025-01-15T12:05:00.000Z",
  "sequenceNumber": 8,
  "result": {
    "labResults": [
      {
        "name": "Creatinine",
        "value": "1.8 mg/dL",
        "flag": "High",
        "referenceRange": "0.7-1.3 mg/dL",
        "date": "2025-01-15",
        "category": "Renal"
      }
    ],
    "patientResponse": "Your kidney function tests show...",
    "clinicianResponse": "The patient demonstrates Stage 3b CKD...",
    "citations": {
      "patient": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
          "title": "KDIGO Guidelines for CKD Management",
          "metadata": { "type": "pubmed" }
        },
        "2": {
          "url": "https://doi.org/10.1016/j.kint.2024.01.006",
          "title": "KDIGO 2024 Clinical Practice Guideline for CKD Evaluation and Management",
          "metadata": {
            "type": "guideline",
            "source": "KDIGO",
            "doi": "10.1016/j.kint.2024.01.006",
            "specialties": ["Nephrology"]
          }
        },
        "3": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/34567890/",
          "title": "Creatinine Clearance as a Marker of GFR in CKD",
          "metadata": {
            "type": "insight",
            "source": "pubmed.ncbi.nlm.nih.gov",
            "author": "Published in Kidney International",
            "pubdate": "2023"
          }
        }
      },
      "clinician": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/87654321/",
          "title": "CKD Progression Risk Factors",
          "metadata": { "type": "pubmed" }
        },
        "2": {
          "url": "https://doi.org/10.1016/j.kint.2024.01.006",
          "title": "KDIGO 2024 Clinical Practice Guideline for CKD Evaluation and Management",
          "metadata": {
            "type": "guideline",
            "source": "KDIGO",
            "doi": "10.1016/j.kint.2024.01.006",
            "specialties": ["Nephrology"]
          }
        }
      }
    },
    "metadata": {
      "labsReceived": 15,
      "labsAnalyzed": 15,
      "insightsMatched": 8
    }
  }
}
```

### Result Fields

| Field                      | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| `labResults`               | Labs that were analyzed (after 200-lab limiting)                                  |
| `patientResponse`          | Patient-friendly explanation in Markdown                                          |
| `clinicianResponse`        | Clinical interpretation with citations in Markdown                                |
| `citations`                | Citation metadata for both responses                                              |
| `metadata.labsReceived`    | Number of labs sent in request                                                    |
| `metadata.labsAnalyzed`    | Number of labs analyzed (after limiting)                                          |
| `metadata.insightsMatched` | Number of curated medical knowledge insights matched to the patient's lab results |

<Note>
  The response format is similar to the EHR Agent but **does not include `selectedElements`** since all provided labs are analyzed directly.
</Note>

## Processing Steps

The Lab Results Agent sends status updates during processing:

| Step | Name                                                 |
| ---- | ---------------------------------------------------- |
| 1    | Processing started                                   |
| 2    | Analyzing lab results                                |
| 3    | Prioritizing findings                                |
| 4    | Generating search queries                            |
| 5    | Searching medical literature and clinical guidelines |
| 6    | Processing search results                            |
| 7    | Generating responses                                 |
| 8    | Final webhook delivered                              |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.heliosai.health/api/v1/lab-results \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "webhookUrl": "https://your-server.com/webhook/helios",
      "labResults": [
        {
          "name": "Hemoglobin A1c",
          "value": "7.2%",
          "flag": "High",
          "referenceRange": "4.0-5.6%",
          "date": "2025-01-15"
        },
        {
          "name": "Fasting Glucose",
          "value": "142 mg/dL",
          "flag": "High",
          "referenceRange": "70-99 mg/dL",
          "date": "2025-01-15"
        }
      ],
      "patientContext": {
        "age": "52",
        "gender": "female",
        "conditions": [
          { "name": "Type 2 Diabetes Mellitus", "status": "active" }
        ],
        "medications": [
          { "name": "Metformin", "dosage": "500mg", "frequency": "twice daily" }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.heliosai.health/api/v1/lab-results', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      webhookUrl: 'https://your-server.com/webhook/helios',
      labResults: [
        {
          name: 'Hemoglobin A1c',
          value: '7.2%',
          flag: 'High',
          referenceRange: '4.0-5.6%',
          date: '2025-01-15'
        },
        {
          name: 'Fasting Glucose',
          value: '142 mg/dL',
          flag: 'High',
          referenceRange: '70-99 mg/dL',
          date: '2025-01-15'
        }
      ],
      patientContext: {
        age: '52',
        gender: 'female',
        conditions: [
          { name: 'Type 2 Diabetes Mellitus', status: 'active' }
        ],
        medications: [
          { name: 'Metformin', dosage: '500mg', frequency: 'twice daily' }
        ]
      }
    })
  });

  const { runId, status } = await response.json();
  console.log(`Request accepted with runId: ${runId}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.heliosai.health/api/v1/lab-results',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'webhookUrl': 'https://your-server.com/webhook/helios',
          'labResults': [
              {
                  'name': 'Hemoglobin A1c',
                  'value': '7.2%',
                  'flag': 'High',
                  'referenceRange': '4.0-5.6%',
                  'date': '2025-01-15'
              },
              {
                  'name': 'Fasting Glucose',
                  'value': '142 mg/dL',
                  'flag': 'High',
                  'referenceRange': '70-99 mg/dL',
                  'date': '2025-01-15'
              }
          ],
          'patientContext': {
              'age': '52',
              'gender': 'female',
              'conditions': [
                  {'name': 'Type 2 Diabetes Mellitus', 'status': 'active'}
              ],
              'medications': [
                  {'name': 'Metformin', 'dosage': '500mg', 'frequency': 'twice daily'}
              ]
          }
      }
  )

  data = response.json()
  print(f"Request accepted with runId: {data['runId']}")
  ```
</CodeGroup>

## Element Limits

| Category       | Max Elements |
| -------------- | ------------ |
| Lab Results    | 200          |
| Conditions     | 100          |
| Medications    | 30           |
| Allergies      | 20           |
| Family History | 20           |

## Pricing

**\$0.65 per request**

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Set up webhook handling and signature verification.
  </Card>

  <Card title="Response Format" icon="file-lines" href="/response-format">
    Learn how to parse and display responses.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/rate-limits">
    Understand concurrency limits.
  </Card>

  <Card title="EHR Agent" icon="file-medical" href="/api-reference/ehr-agent">
    See the EHR Agent for comprehensive health analysis.
  </Card>
</CardGroup>