Lab Results Agent

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

Best for:

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

Input: Lab results + optional patient context

EHR Agent

Best for:

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

Input: Full EHR data bundle

Endpoint

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

Request Format

{
  "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

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.

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

{
  "error": "Validation error",
  "details": [
    { "path": "labResults", "message": "Required" }
  ]
}

401 Unauthorized

{
  "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).

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

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Response Format

Immediate Response (200 OK)

{
  "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:

{
  "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

The response format is similar to the EHR Agent but does not include selectedElements since all provided labs are analyzed directly.

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

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" }
      ]
    }
  }'

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}`);

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']}")

Element Limits

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

Pricing

$0.65 per request

Next Steps

Webhooks

Set up webhook handling and signature verification.

Response Format

Learn how to parse and display responses.

Rate Limits

Understand concurrency limits.

EHR Agent

See the EHR Agent for comprehensive health analysis.

Overview

Agents

API Reference

Lab Results Agent

When to Use