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
Lab Results Agent 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 bundleEndpoint 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 webhookUrlstring HTTPS URL to receive results labResultsarray Lab test results to analyze (min 1, max 200)
Lab Result Fields Field Type Required Description namestring Yes Lab test name (e.g., “Creatinine”, “Hemoglobin A1c”) valuestring Yes Result value, may include unit (e.g., “1.8 mg/dL” or “7.2%“) flagstring No Abnormality flag: High, Low, Normal, Critical referenceRangestring No Normal reference range (e.g., “0.7-1.3 mg/dL”) datestring No Date of test (ISO 8601 or YYYY-MM-DD). Recommended unitstring No Unit of measurement (if not in value) categorystring No Lab category for database matching (e.g., “Renal”, “Metabolic”) notesstring 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 namestring - Patient name or identifier agestring - Patient age genderstring - Patient gender conditionsarray 100 Medical conditions/diagnoses medicationsarray 30 Current medications allergiesarray 20 Known allergies familyHistoryarray 20 Family medical history vitalSignsarray - Recent vital signs socialHistorystring - Smoking, alcohol, diet, exercise clinicalNotesstring - 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." }
Header Description Example X-Concurrent-LimitMaximum concurrent requests 7X-Concurrent-ActiveActive requests (including this one) 2X-Concurrent-RemainingAvailable 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 labResultsLabs that were analyzed (after 200-lab limiting) patientResponsePatient-friendly explanation in Markdown clinicianResponseClinical interpretation with citations in Markdown citationsCitation metadata for both responses metadata.labsReceivedNumber of labs sent in request metadata.labsAnalyzedNumber of labs analyzed (after limiting) metadata.insightsMatchedNumber 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" } ] } }'
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.
