# Attribute a downstream patient or system outcome to a prior inference Source: https://medlogprotocol.ai/api-reference/events/attribute-a-downstream-patient-or-system-outcome-to-a-prior-inference /api-reference/openapi.yaml post /event/outcome # Record a new internal model artifact Source: https://medlogprotocol.ai/api-reference/events/record-a-new-internal-model-artifact /api-reference/openapi.yaml post /event/internal-artifact # Record content shown to a human user Source: https://medlogprotocol.ai/api-reference/events/record-content-shown-to-a-human-user /api-reference/openapi.yaml post /event/human-output # Record explicit user feedback Source: https://medlogprotocol.ai/api-reference/events/record-explicit-user-feedback /api-reference/openapi.yaml post /event/user-feedback # Record the beginning of an inference run Source: https://medlogprotocol.ai/api-reference/events/record-the-beginning-of-an-inference-run /api-reference/openapi.yaml post /event/inference-start # API reference Source: https://medlogprotocol.ai/api-reference/overview The five write-once event endpoints that assemble a MedLog record. The MedLog API is a set of **write-once event endpoints**. A collector accepts events but never returns record contents — each call appends one schema-compliant message that is later assembled into a complete [record](/specification/overview). The interactive endpoint pages in this section are generated directly from the [OpenAPI specification](https://github.com/mims-harvard/medlog). ## Authentication All endpoints require an API key passed in the **`X-API-Key`** header. ```bash theme={null} curl -X POST https://your-collector.example.org/event/inference-start \ -H "X-API-Key: $MEDLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ ... }' ``` ## Endpoints Each endpoint records one part of a MedLog record: | Method | Path | Records | | ------ | -------------------------- | ------------------------------------------------------------------------ | | `POST` | `/event/inference-start` | The beginning of an inference run — creates the `event_id` and `run_id`. | | `POST` | `/event/internal-artifact` | An intermediate artifact (reasoning trace, retrieved context, …). | | `POST` | `/event/human-output` | Content shown to a human user. | | `POST` | `/event/outcome` | A downstream patient or system outcome attributed to a prior inference. | | `POST` | `/event/user-feedback` | Explicit user feedback. | Select an endpoint in the sidebar to see its full schema and try it against a server using the built-in API playground. ## The event model Every event extends a shared **`BaseEvent`** and adds an event-specific payload. The base fields carry identity and linkage: | Field | Type | Notes | | ----------------- | --------- | -------------------------------------------------------------- | | `event_id` | uuid | Unique ID for this event. **Required.** | | `run_id` | uuid | Constant across all events in the same run. | | `parent_event_id` | uuid | The event this one expands on. | | `timestamp` | date-time | When the event occurred. **Required.** | | `medlog_version` | string | Protocol version. **Required.** | | `system_metadata` | object | `hostname`, `app_name`, `proc_id`, `latency_ms`. **Required.** | The first event (`inference-start`) additionally carries the model instance, user and target identities, and inputs. Later events carry a single typed payload — an `artifact`, `output`, `outcome`, or `feedback` object. See [the record fields](/specification/overview) for the conceptual model behind these payloads. ## Responses | Status | Meaning | | ------ | ------------------------------------------------ | | `201` | Event accepted. | | `400` | Bad request — invalid payload or missing fields. | | `401` | Unauthorized — missing or invalid credentials. | | `403` | Forbidden — insufficient permissions. | Error responses return an `Error` object with a `message`, and optionally a `code` and `details`. # Citation Source: https://medlogprotocol.ai/citation If you use MedLog in your research, please cite our preprint. arXiv:2510.04033 \[cs.AI] · doi:10.48550/arXiv.2510.04033 Ayush Noori, Aaron E. Boussina, Hai Ho Bich, James Anibal, Julia Maslinski, Manuel Burger, Martin Faltys, Adam Rodman, Alan Karthikesalingam, Alessandro Blasimme, Annelia Itwaru, Ben Kaplan, Bilal A. Mateen, Christopher A. Longhurst, Daniel Yang, Dave deBronkart, Effy Vayena, Fedor Sergeev, Gauden Galea, Ha Thi Hai Duong, Harold F. Wolf III, Jacob Waxman, Joerg C. Schefold, Joshua C. Mandel, Juliana Rotich, Kenneth D. Mandl, Lily Poursoltan, Maryam Mustafa, Melissa Miles, Nigam H. Shah, Noa Dagan, Pavan Bodanki, Peter Lee, Philipp Koralus, Prathamesh Parchure, Prem Timsina, Ran D. Balicer, Robert Korom, Scott Mahoney, Seth Hain, Tien Yin Wong, Trevor Mundel, Vivek Natarajan, Ankit Sakhuja, Benjamin Glicksberg, C. Louise Thwaites, Gunnar Rätsch, Karandeep Singh, David A. Clifton, Isaac S. Kohane, Marinka Zitnik. A global log for medical AI. arXiv: 2510.04033 \[cs.AI]. Published online 2025. Under review. doi: 10.48550/arXiv.2510.04033 ```bibtex theme={null} @misc{noori_global_2025, title = {A global log for medical {AI}}, url = {http://arxiv.org/abs/2510.04033}, doi = {10.48550/arXiv.2510.04033}, urldate = {2026-01-24}, publisher = {arXiv}, author = {Noori, Ayush and Boussina, Aaron E. and {Hai Ho Bich} and Anibal, James and Maslinski, Julia and Burger, Manuel and Faltys, Martin and Rodman, Adam and Karthikesalingam, Alan and Blasimme, Alessandro and Itwaru, Annelia and Kaplan, Ben and Mateen, Bilal A. and Longhurst, Christopher A. and Yang, Daniel and deBronkart, Dave and Vayena, Effy and Sergeev, Fedor and Galea, Gauden and {Ha Thi Hai Duong} and Wolf, Harold F. and Waxman, Jacob and Schefold, Joerg C. and Mandel, Joshua C. and Rotich, Juliana and Mandl, Kenneth D. and Poursoltan, Lily and Mustafa, Maryam and Miles, Melissa and Shah, Nigam H. and Dagan, Noa and Bodanki, Pavan and Lee, Peter and Koralus, Philipp and Parchure, Prathamesh and Timsina, Prem and Balicer, Ran D. and Korom, Robert and Mahoney, Scott and Hain, Seth and Wong, Tien Yin and Mundel, Trevor and Natarajan, Vivek and Sakhuja, Ankit and Glicksberg, Benjamin and Thwaites, C. Louise and Rätsch, Gunnar and Singh, Karandeep and Clifton, David A. and Kohane, Isaac S. and Zitnik, Marinka}, month = oct, year = {2025}, note = {arXiv:2510.04033 [cs]}, } ``` # Deployments Source: https://medlogprotocol.ai/deployments/overview Four clinical deployments monitored with MedLog. We evaluate MedLog across four clinical deployments spanning intensive care monitoring, infectious disease severity prediction, hospital quality reporting, and patient attendance prediction. MedLog makes model behavior visible in practice. It reveals patterns that offline evaluation does not capture, including temporal failure modes, workflow-dependent variability, interactions between model outputs and clinician behavior, and performance degradation during severe weather events. A prospective three-month pilot monitoring the BEACON early-warning model in the ICU at the University Hospital of Bern, generating early warnings of circulatory and respiratory failure. Monitoring an AI model that predicts tetanus progression from wearable physiological waveforms at the Hospital for Tropical Diseases. Logging a deployed LLM system for automated SEP-1 sepsis quality reporting at UC San Diego Health. Population-scale monitoring of a patient-attendance prediction model across the Mount Sinai Health System. | Location | Duration | Number of patients | Median age (IQR) | No. MedLog records | | -------------------------- | -------- | ------------------------------------- | --------------------- | -----------------: | | Bern, Switzerland | 114 days | 212 (148 M, 64 F) | 68.00 (55.80 – 77.00) | 223,840 | | Ho Chi Minh City, Vietnam | 289 days | 15 (14 M, 1 F) | 49.94 (47.03 – 60.54) | 3,406 | | San Diego, California, USA | 89 days | 60 (28 M, 32 F) | 64.00 (54.00 – 71.25) | 3,766 | | New York, New York, USA | 244 days | 791,319 (324,294 M, 466,626 F, 399 O) | 54.00 (36.00 – 68.00) | 2,914,264 | # Get involved Source: https://medlogprotocol.ai/get-involved Share feedback, join the team, or pilot MedLog at your institution. Interested in sharing feedback about the MedLog protocol design, joining the MedLog team, or piloting MedLog to monitor a deployed health AI model at your institution? Please fill out the form below or contact [Ayush Noori](mailto:ayush.noori@sjc.ox.ac.uk), [Zak Kohane](mailto:isaac_kohane@hms.harvard.edu), and [Marinka Zitnik](mailto:marinka@hms.harvard.edu). # Integration patterns Source: https://medlogprotocol.ai/implementation/integration Integrate MedLog at API gateways, LLM proxies, and agent frameworks — without modifying the models. MedLog can be deployed within a health system without coordination with external institutions or vendors. Cross-site analysis, however, requires shared interfaces across EHR vendors, AI vendors, and health systems. MedLog can be integrated into existing systems at **API gateways, LLM proxies, or similar interfaces that intercept model calls** and emit MedLog-compliant records. The same approach can wrap agent frameworks and tool calls to record inputs, retrieved context, outputs, and uncertainty estimates. This design supports incremental adoption without modifying the underlying models. ```mermaid theme={null} flowchart LR CALLER["Clinician app /
service / agent"] --> GW["API gateway /
LLM proxy"] GW --> MODEL["AI model"] MODEL --> GW GW --> CALLER GW -. MedLog-compliant records .-> COL["MedLog collector"] ``` ## Implemented with existing tooling MedLog can be implemented with existing standards and tooling. Existing standards can represent its logging patterns without requiring a new software stack. See [interoperability](/interoperability/overview) for how MedLog maps onto W3C PROV, OpenLineage, USCDI, FHIR, and OpenTelemetry, or jump straight to the [field mapping explorer](/interoperability/field-mapping). # Low-resource settings Source: https://medlogprotocol.ai/implementation/low-resource MedLog scales down to settings without full EHR infrastructure or continuous connectivity. MedLog can be implemented in low- and lower-middle-income settings without requiring full EHR infrastructure or continuous connectivity. ## Minimal implementation A minimal implementation can record only a small set of fields, such as [Header](/specification/header), [Model instance](/specification/model-instance), and [Outputs](/specification/outputs), and add further fields as local capacity grows. ## Intermittent connectivity When network access is intermittent, local write-behind caching can store records on device and synchronize them once connectivity returns. ## Without an EHR Where EHR systems are unavailable, MedLog records can instead link to encounter-level metadata such as time, location, and department, with optional [FHIR](/implementation/interoperability#fhir) integration when available. ## Open-source platforms MedLog can also connect to platforms such as **OpenMRS** and **DHIS2**. # Storage and retention Source: https://medlogprotocol.ai/implementation/storage-retention Logging volume depends on workflow design; retention policies keep it manageable. Recording model use creates substantial storage and data management requirements. Logging volume depends on workflow design, inference frequency, deployment duration, and operational scale. These requirements are consistent with broader trends in healthcare data generation, which is projected to exceed **10,800 exabytes annually by 2025**, with a single hospitalization producing on the order of **150,000 data elements**. MedLog extends existing clinical data systems by recording model inputs, outputs, metadata, and optional execution traces associated with AI use. ## Retention strategies Institutions may retain all MedLog records for retrospective analysis or apply selective retention policies to manage storage, cost, and operational requirements. Retention strategies include: During pilot studies or after major model updates. During steady-state deployment. With long-term summaries and shorter-lived detailed artifacts. # What is MedLog? Source: https://medlogprotocol.ai/index A protocol for event-level logging of medical AI. Artificial intelligence (AI) is rapidly entering clinical settings in a fragmented and largely unregulated manner. As of May 2025, at least 377 healthcare systems and providers in the U.S. have piloted or adopted 70 generative AI tools developed by 49 companies for clinical decision support, patient communication, documentation, claims processing, and healthcare administration. The majority of American physicians report using AI technologies in clinical care. Similar trends are observed globally: 48% of clinicians across 109 countries report AI use in their work, and large-scale deployments are emerging across health systems in China. This adoption reflects the strong performance of modern AI models on largely synthetic benchmarks. Large language models (LLMs) match or exceed physician performance in diagnostic reasoning, clinical text summarization, medical question answering, patient communication, and multi-step reasoning tasks. However, concerns about hallucinations, bias, and reliability remain. Real-world clinical performance remains poorly understood. More realistic benchmarks are emerging, but systematic evaluation in deployed settings remains rare. A central limitation is the lack of logging for each instance in which a medical AI model is used. Without consistent records of how models are used in practice, health systems cannot reliably assess performance, detect failure modes, or measure clinical impact. Reporting frameworks, including TRIPOD+AI, STARD-AI, DECIDE-AI, SPIRIT-AI, and CONSORT-AI, focus on model development and evaluation in controlled settings. They do not address continuous, event-level monitoring of deployed systems, especially generative AI and agentic workflows that rely on prompting, retrieval, and tool use. Several governance and evaluation frameworks have also been proposed. However, no broadly adopted standard records each instance of AI use in clinical care. This gap limits the ability to evaluate medical AI in practice and to govern its use. The FDA has emphasized that clinicians cannot feasibly oversee all outputs of generative AI systems. Medical AI therefore requires systematic monitoring. In other domains, centralized logging protocols such as `syslog` fill this role by recording each system event in a consistent way across many connected services. These logs support real-time monitoring, root-cause analysis, and auditing at scale. Medical AI has no equivalent standard. Here we introduce MedLog, a protocol for event-level logging of medical AI. MedLog specifies a schema for each model invocation, including inputs, outputs, intermediate artifacts, and, when available, clinical outcomes and user feedback. It records both single-step interactions and multi-stage agentic workflows by linking events over time. MedLog covers any AI process that uses health data and can affect patient outcomes, including AI-human and AI-AI interactions. This includes interactions between models and patients, clinicians, administrators, and other stakeholders; background services such as batch inference, autonomous triage, claim routing, and continuous monitoring; and AI-AI exchanges within agentic workflows and orchestration frameworks. Examples of medical AI interactions that can be logged under the MedLog protocol, as well as the MedLog records they create.
Examples of medical AI interactions that can be logged under the MedLog protocol, as well as the MedLog records they create.
We evaluate MedLog across four clinical deployments spanning intensive care monitoring, infectious disease severity prediction, hospital quality reporting, and patient attendance prediction. MedLog makes model behavior visible in practice. It reveals patterns that offline evaluation does not capture, including temporal failure modes, workflow-dependent variability, interactions between model outputs and clinician behavior, and performance degradation during severe weather events. By standardizing how health systems record AI use and link it to outcomes, MedLog creates a basis for continuous evaluation, auditing, and improvement of medical AI. As AI becomes embedded in clinical workflows, this infrastructure will be needed to measure real-world performance, detect failures, and guide deployment at scale. Emit your first MedLog record in a few API calls. The nine fields of every MedLog record. Four clinical deployments monitored with MedLog. Write-once event endpoints with an interactive playground. # Relationship to EHR audit logs Source: https://medlogprotocol.ai/interoperability/audit-logs What a decade of EHR audit log research implies for real-world MedLog deployment. MedLog also builds on EHR audit logs. EHRs often maintain event or audit logs for record access. These logs demonstrate that **event-level logging in healthcare is feasible at scale**: audit logs can capture time-stamped user actions, measure clinical work, and reveal aspects of care delivery that are not visible from clinical or claims data alone. ## What audit log research has shown Audit logs have been used to assess hospital workflow efficiency. Interaction patterns in audit logs have been associated with length of stay and timeliness of care. Audit logs support detection of clinical outliers. Audit logs have been used to study provider behavior directly. Audit logs have also revealed contextual factors relevant to clinical process outcomes across multiple sites, even despite site-dependent documentation differences. ## Why this matters for MedLog These past studies of EHR auditing and logging can provide learnings for real-world deployment of MedLog beyond the pilots reported in the [MedLog paper](https://arxiv.org/abs/2510.04033). They establish both the feasibility of health-system-scale event logging and the analytic value of linking time-stamped events to care delivery. MedLog [Outcomes](/specification/outcomes) may themselves include traces of how patients or clinicians interact with the EHR after viewing AI outputs, as recorded in EHR audit logs. # Field mapping explorer Source: https://medlogprotocol.ai/interoperability/field-mapping An interactive map from each MedLog field to related USCDI concepts and FHIR and OpenTelemetry representations. Select a MedLog field below to see the **related USCDI concepts** and **FHIR and OpenTelemetry representations** for that field. Every element links to its own documentation.
Available at invocation
Appended later
Available at invocation
Header
Provenance information, execution context, and system metadata available at inference time.
Read the field reference
USCDI
Provenance information, including Author Time Stamp and Author Organization, where relevant. These concepts do not substitute for model-inference or audit-recording times.
FHIR R5
AuditEvent.occurredPeriod can represent the execution interval, while AuditEvent.recorded records when the audit event was logged. AuditEvent.source.observer can identify the reporting source. MedLog-specific invocation identifiers, protocol version, parent-event linkage, and other workflow context can remain in the linked MedLog payload or defined extensions.
OpenTelemetry
OpenTelemetry log Timestamp and ObservedTimestamp can distinguish source-event and collection times. Populate trace and span identifiers only when genuine tracing context exists; use gen\_ai.conversation.id only when the MedLog run identifier has the same conversation or thread scope.
Available at invocation
Model instance
Stable identifiers of the AI model and version, with references to its model card and data sheet.
Read the field reference
USCDI
No direct counterpart
No direct counterpart for the complete AI-specific configuration of a model invocation.
FHIR R5
A software model can be represented by a Device. Device.identifier can identify the software instance, while Device.version.value can record its software version. Model-card references, training-data versions, deployment identifiers, test-time modifications, and other invocation-specific configuration can remain in the linked MedLog payload or associated documentation.
OpenTelemetry
Preserve richer model metadata under medlog.model\_instance.\*. For generative AI, gen\_ai.request.model can identify the requested model and gen\_ai.response.model the responding model when independently known. These attributes do not replace model-version, deployment, or other configuration metadata.
Available at invocation
User identity
The technical process, service, or workflow that invokes the model call.
Read the field reference
USCDI
Provenance Author, Author Role, and Author Organization; Care Team Members and facility information where applicable. Authorship and initiation of a model invocation are distinct concepts.
FHIR R5
AuditEvent.agent can represent actors involved in the event. AuditEvent.agent.who.identifier can preserve a native account identifier and namespace, while AuditEvent.agent.role can record the active security role. References to Practitioner or PractitionerRole can add human, clinical-role, and organizational context. Session or login context not represented directly can remain in MedLog.
OpenTelemetry
Preserve the full provenance chain in medlog.user\_identity.\*. Compatible application context can additionally use user.id, user.name, and session.id. These attributes do not replace identifier namespaces, caller ordering, or other MedLog-specific provenance information.
Available at invocation
Target identity
A reference to the entity about which the model produces output.
Read the field reference
USCDI
Patient Identifier and encounter or appointment information where applicable.
FHIR R5
AuditEvent.patient can identify a patient whose data were involved in the event, and AuditEvent.encounter can provide encounter context. AuditEvent.entity.what can reference other relevant target or contextual resources, such as an Appointment. When provenance of a generated or updated FHIR resource is being described, Provenance.target identifies that resource.
OpenTelemetry
Preserve target type, identifier namespace, and clinical references in medlog.target\_identity.\*. Do not populate user.id merely because the target is a patient; being the subject of a prediction does not establish participation as an application user.
Available at invocation
Inputs
The input data provided to the model, including prompts, structured fields, and feature vectors.
Read the field reference
USCDI
Laboratory, Vital Signs, Medications, Problems, Clinical Notes, Diagnostic Imaging, and other clinical data used by the model.
FHIR R5
Inputs can reference resources matching their clinical meaning, including Observation, DocumentReference, Condition, and MedicationRequest. Provenance.entity.what can identify source entities used in producing an output. Input versions, preprocessing state, feature vectors, prompts, or other information needed for reconstruction can remain in MedLog.
OpenTelemetry
Retain inputs or controlled-access references in the structured MedLog payload. For generative AI, compatible chat history can use gen\_ai.input.messages, while separately supplied system instructions can use gen\_ai.system\_instructions. Arbitrary feature vectors or clinical variables should not be relabeled as messages solely to fit Gen AI conventions.
Appended later
Internal artifacts
Artifacts generated during inference, such as reasoning traces, retrieved context, and uncertainty estimates.
Read the field reference
USCDI
No direct counterpart
No direct counterpart for AI execution traces, tool calls, retrieval results, attribution maps, or invocation-specific state.
FHIR R5
A DocumentReference can reference stored artifacts; for example, DocumentReference.content.attachment.url can point to controlled-access artifact storage. Artifact type, format, version, and linkage to the originating invocation can remain in MedLog or explicitly defined extensions.
OpenTelemetry
Preserve artifact metadata and payloads or references in medlog.artifact.\*. Compatible generative-AI operations can additionally use semantic conventions such as gen\_ai.tool.name and gen\_ai.retrieval.documents. Other internal artifacts remain MedLog-specific.
Appended later
Patient- or clinician-facing outputs
The outputs intended for human users, including predictions, generated content, explanations, and recommendations.
Read the field reference
USCDI
Clinical Notes or other USCDI elements corresponding to the output's actual clinical meaning; there is no universal AI-output element.
FHIR R5
Use resources corresponding to the output's clinical meaning, such as RiskAssessment for a clinical risk prediction or DocumentReference for a generated document. Provenance.target can identify a resource generated or updated by the activity. The original model output should remain distinguishable from subsequent human edits, transformations, and presentation events.
OpenTelemetry
Preserve outputs in medlog.output.\*. For generative AI, corresponding model-response messages can use gen\_ai.output.messages. gen\_ai.output.type describes the output type requested by the client and should not be treated as an unconditional equivalent of a MedLog output-type field.
Appended later
Outcomes
Records of clinical actions or patient outcomes linked to the model recommendation.
Read the field reference
USCDI
Adverse Events, orders, Medications, Problems, Laboratory results, and other elements corresponding to the clinical or operational endpoint being measured.
FHIR R5
Outcomes can reference resources matching their clinical meaning, such as ServiceRequest or MedicationRequest for orders, MedicationAdministration for administered therapy, Condition or Observation for clinical endpoints, and Appointment.status for attendance. Linkage between the outcome and originating AI interaction remains explicit in MedLog. AuditEvent.outcome records the success or failure of the audited event and is not itself a clinical outcome.
OpenTelemetry
Preserve endpoint values, times, clinical references, and linkage evidence in medlog.outcome.\*. Delayed outcomes can be emitted as later records linked to the originating invocation. Clinical benefit or harm should not be represented as inference execution status, nor should an execution span remain open while awaiting clinical follow-up.
Appended later
User feedback
Any feedback provided by users, whether structured ratings or free-text comments.
Read the field reference
USCDI
No direct counterpart
No direct counterpart for AI-specific feedback; clinical assessment data are not automatically equivalent to feedback on an AI interaction.
FHIR R5
QuestionnaireResponse can represent feedback collected through a defined questionnaire. Its author, subject, encounter, and questionnaire linkage can provide additional context where applicable. Other ratings or comments can remain in a linked MedLog payload. Preserve the feedback instrument and version, respondent attribution, and explicit linkage to the invocation or output.
OpenTelemetry
Preserve feedback in medlog.feedback.\*. Feedback explicitly evaluating a generative-AI response can additionally use gen\_ai.evaluation.name together with gen\_ai.evaluation.score.value or gen\_ai.evaluation.score.label where applicable. General comments should not be converted into an artificial score.
USCDI data classes and elements FHIR R5 resources and elements OpenTelemetry attributes MedLog-specific attributes
## How to read this map USCDI entries identify **related data concepts** rather than exact equivalents or an audit-event schema. FHIR examples use [Release 5 (5.0.0)](https://hl7.org/fhir/R5/). OpenTelemetry mappings are conditional on matching semantics, available source information, and capture policy. The `medlog.*` namespace denotes MedLog-specific attributes for concepts not captured by existing semantic conventions. **These derived attributes do not replace the canonical MedLog payload** — they make a MedLog record legible to tooling that already speaks these standards. A mapping is only appropriate when the semantics genuinely match. Several fields have no direct counterpart in USCDI, and reusing an attribute whose meaning differs — for example, recording a patient who is the subject of a prediction as an application `user.id` — produces records that look standards-compliant but describe something that did not happen. # Health data elements Source: https://medlogprotocol.ai/interoperability/health-data Reusing USCDI data classes and FHIR resources to anchor MedLog records to standardized clinical entities. ## USCDI [USCDI](https://isp.healthit.gov/united-states-core-data-interoperability-uscdi) defines data classes and elements for interoperable health information exchange. These elements can be reused within MedLog records. | MedLog field | Related USCDI concepts | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [User identity](/specification/user-identity) | [Care Team Members](https://isp.healthit.gov/uscdi-data-class/care-team-members) and [Facility Information](https://isp.healthit.gov/uscdi-data-class/facility-information) | | [Target identity](/specification/target-identity) | [Patient](https://isp.healthit.gov/uscdi-data-class/patient-demographicsinformation) and [Encounter](https://isp.healthit.gov/uscdi-data-class/encounter-information) identifiers | | [Inputs](/specification/inputs) | [Laboratory](https://isp.healthit.gov/uscdi-data-class/laboratory), [Vital Signs](https://isp.healthit.gov/uscdi-data-class/vital-signs), [Medications](https://isp.healthit.gov/uscdi-data-class/medications), [Clinical Notes](https://isp.healthit.gov/uscdi-data-class/clinical-notes), and [Diagnostic Imaging](https://isp.healthit.gov/uscdi-data-class/diagnostic-imaging) | | [Outcomes](/specification/outcomes) | [Adverse Events](https://isp.healthit.gov/uscdi-data/adverse-event) | ## FHIR [Fast Healthcare Interoperability Resources (FHIR)](https://hl7.org/fhir/) data formats and elements can also anchor MedLog entries to standardized clinical entities. [`AuditEvent.occurredPeriod`](https://hl7.org/fhir/R5/auditevent.html) can represent the execution interval and [`AuditEvent.recorded`](https://hl7.org/fhir/R5/auditevent-definitions.html#AuditEvent.recorded) can record when the MedLog record was logged. [`AuditEvent.agent`](https://hl7.org/fhir/R5/auditevent-definitions.html#AuditEvent.agent) can identify the immediate calling service, with the account identifier recorded in [`AuditEvent.agent.who.identifier`](https://hl7.org/fhir/R5/auditevent-definitions.html#AuditEvent.agent.who) and security role in [`AuditEvent.agent.role`](https://hl7.org/fhir/R5/auditevent-definitions.html#AuditEvent.agent.role). When possible, references to [`Practitioner`](https://hl7.org/fhir/R5/practitioner.html) or [`PractitionerRole`](https://hl7.org/fhir/R5/practitionerrole.html) can link the account to the human user and clinical role context. Target identity can reference an existing [`Patient`](https://hl7.org/fhir/R5/patient.html), [`Appointment`](https://hl7.org/fhir/R5/appointment.html), or other appropriate resource, with [`Encounter`](https://hl7.org/fhir/R5/encounter.html) providing encounter context where applicable. A software model can be represented by a [`Device`](https://hl7.org/fhir/R5/device.html) containing its identifier and software version. Inputs can reference [`Observation`](https://hl7.org/fhir/R5/observation.html) or [`DocumentReference`](https://hl7.org/fhir/R5/documentreference.html), for example, while outputs can use FHIR resources appropriate to their clinical meaning, such as [`RiskAssessment`](https://hl7.org/fhir/R5/riskassessment.html) for a risk prediction or `DocumentReference` for a generated document. User feedback collected through a defined questionnaire can use [`QuestionnaireResponse`](https://hl7.org/fhir/R5/questionnaireresponse.html). These are only illustrative examples of the many possible FHIR fields which could be used to represent or reference information in MedLog records. The [field mapping explorer](/interoperability/field-mapping) shows the full set side by side with USCDI and OpenTelemetry. # Interoperability Source: https://medlogprotocol.ai/interoperability/overview MedLog can be implemented using existing open standards and tooling. MedLog can be implemented using existing open standards and tooling. The MedLog protocol defines **what information should be recorded** at each invocation of a medical AI model; existing frameworks provide complementary ways to **represent, exchange, and analyze** that information. ```mermaid theme={null} flowchart LR REC["MedLog record
(nine fields)"] --> PROV["W3C PROV · OpenLineage
provenance and lineage"] REC --> HD["USCDI · FHIR
health data elements"] REC --> OTEL["OpenTelemetry
operational telemetry"] PROV --> USE["Vendor-agnostic deployment,
multi-institutional analysis"] HD --> USE OTEL --> USE ``` ## The layers [W3C PROV](https://www.w3.org/TR/prov-o/) provides a conceptual model for computational provenance, and [OpenLineage](https://openlineage.io/) supports lineage tracking across institutional workflows. [USCDI](https://isp.healthit.gov/united-states-core-data-interoperability-uscdi) defines high-level health data classes and elements, and [FHIR](https://hl7.org/fhir/) provides structured resource representations. [OpenTelemetry](https://opentelemetry.io/) supports operational telemetry, with collectors that transport and store event data across languages and platforms. Event-level logging already runs at scale in healthcare. EHR audit logs offer a decade of learnings for real-world MedLog deployment. These interoperability layers enable **scalable, vendor-agnostic deployments** and lower the barrier to multi-institutional analyses. ## Explore the mappings Select any of the nine MedLog fields to see related USCDI concepts and FHIR and OpenTelemetry representations, each linked to its documentation. The mappings throughout this section are **illustrative, not normative**. They identify related concepts rather than exact equivalents, and they are conditional on matching semantics, available source information, and local capture policy. None of them replace the canonical MedLog payload. # Provenance and lineage tracking Source: https://medlogprotocol.ai/interoperability/provenance Representing MedLog records with W3C PROV, and linking them to institutional workflows with OpenLineage. ## W3C PROV MedLog implementations can use the [W3C PROV](https://www.w3.org/TR/prov-o/) conceptual model to distinguish data, activities, and responsible actors. A MedLog record and its fragments can be represented as [`prov:Entity`](https://www.w3.org/TR/prov-o/#Entity) instances; the model invocation itself as a [`prov:Activity`](https://www.w3.org/TR/prov-o/#Activity); and the model and user as instances of [`prov:Agent`](https://www.w3.org/TR/prov-o/#Agent) or its subclasses, such as [`prov:SoftwareAgent`](https://www.w3.org/TR/prov-o/#SoftwareAgent), [`prov:Person`](https://www.w3.org/TR/prov-o/#Person), or [`prov:Organization`](https://www.w3.org/TR/prov-o/#Organization). | MedLog concept | PROV concept | | ------------------------------- | ------------------------------------------------------------------- | | MedLog record and its fragments | [`prov:Entity`](https://www.w3.org/TR/prov-o/#Entity) | | Model invocation | [`prov:Activity`](https://www.w3.org/TR/prov-o/#Activity) | | Model | [`prov:SoftwareAgent`](https://www.w3.org/TR/prov-o/#SoftwareAgent) | | Human user | [`prov:Person`](https://www.w3.org/TR/prov-o/#Person) | | Institution | [`prov:Organization`](https://www.w3.org/TR/prov-o/#Organization) | Relations connect an invocation to its inputs, outputs, and participating actors. | Relation | Connects an invocation to | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [`prov:used`](https://www.w3.org/TR/prov-o/#used) | Its [inputs](/specification/inputs) | | [`prov:wasGeneratedBy`](https://www.w3.org/TR/prov-o/#wasGeneratedBy) | Its [outputs](/specification/outputs) and [internal artifacts](/specification/internal-artifacts) | | [`prov:wasAssociatedWith`](https://www.w3.org/TR/prov-o/#wasAssociatedWith) | The [users](/specification/user-identity) and models that participated | ## OpenLineage [OpenLineage](https://openlineage.io/) can also be used to link AI interactions recorded in MedLog records to broader institutional computational workflows. For example, an inference pipeline can be represented as a **job**, with individual executions represented as **runs** and consumed or produced data represented as **datasets**. OpenLineage `runId` values can be referenced in the MedLog [Header](/specification/header) field, allowing inference events to be linked to upstream data processing steps and downstream computational outputs. Linking a `runId` into the header is what makes an inference event traceable in both directions: back to the data preparation that produced its inputs, and forward to the analyses that consume its outputs. # Telemetry standards Source: https://medlogprotocol.ai/interoperability/telemetry Emitting MedLog records as OpenTelemetry telemetry with a MedLog semantic convention. For operational telemetry, [OpenTelemetry](https://opentelemetry.io/) provides consistent schemas and collectors to transport and store event data across languages and platforms. A MedLog **semantic convention** can be defined as a custom OpenTelemetry registry using [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver), reusing existing OpenTelemetry attributes where their semantics match and defining `medlog.*` attributes for concepts specific to medical AI. ## Reusing Gen AI conventions When logging generative AI models, existing OpenTelemetry [Gen AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/) can be reused. | MedLog field | OpenTelemetry attribute | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `run_id` in the [Header](/specification/header) | [`gen_ai.conversation.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-conversation-id) | | [Model instance](/specification/model-instance) | [`gen_ai.request.model`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-request-model) | | Prompts in [Inputs](/specification/inputs) | [`gen_ai.input.messages`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-input-messages), [`gen_ai.system_instructions`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-system-instructions) | | Responses in [Outputs](/specification/outputs) | [`gen_ai.output.messages`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-output-messages) | | Tool and retrieval operations in [Internal artifacts](/specification/internal-artifacts) | [`gen_ai.tool.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-tool-name), `gen_ai.retrieval.documents` | | Evaluation of output in [User feedback](/specification/user-feedback) | [`gen_ai.evaluation`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-evaluation-name) | Users and sessions can also be represented with existing [User](https://opentelemetry.io/docs/specs/semconv/registry/attributes/user/) and [Session](https://opentelemetry.io/docs/specs/semconv/registry/attributes/session/) semantic conventions such as `user.id` and `user.name`. ## Emitting and collecting records MedLog records can then be emitted as OpenTelemetry telemetry, and an **OpenTelemetry Collector** can receive, process, and export these records to observability platforms. This approach enables integration of MedLog with existing tracing, logging, and monitoring infrastructure. ```mermaid theme={null} flowchart LR APP["Instrumented model
call or gateway"] -- "medlog.* + gen_ai.* attributes" --> COL["OpenTelemetry
Collector"] COL --> OBS["Observability
platform"] COL --> STORE["MedLog record
store"] ``` Derived OpenTelemetry attributes **do not replace** the canonical MedLog payload. Populate trace and span identifiers only when genuine tracing context exists, and reuse an attribute only when its semantics actually match the MedLog field. # Quickstart Source: https://medlogprotocol.ai/quickstart Emit your first MedLog record by writing a stream of events to a collector. A MedLog record is **assembled from a stream of write-once messages** sent to a collector. You do not write a record all at once. Instead, you emit one message at inference start and append more messages as artifacts, outputs, outcomes, and feedback become available. Every message after the first references the original `event_id` (and, for multi-step workflows, a shared `run_id`). This design means a record exists even when inference fails, and lets outcomes or feedback be added later — sometimes hours or days after the model ran. All examples below authenticate with an API key passed in the `X-API-Key` header. Every endpoint is write-only: collectors accept events but never return record contents. ## Emit a record The first message captures everything available at invocation: the [header](/specification/header), [model instance](/specification/model-instance), [user](/specification/user-identity) and [target](/specification/target-identity) identities, and the [inputs](/specification/inputs). It mints the `event_id` (and a `run_id` if this is part of a multi-step workflow). ```bash theme={null} curl -X POST https://your-collector.example.org/event/inference-start \ -H "X-API-Key: $MEDLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_id": "551b1676-1837-4278-988d-59ba3166b83e", "run_id": "492dac48-dd7d-485e-8991-1325e814e73e", "timestamp": "2026-01-10T05:31:19.805Z", "medlog_version": "0.0.1", "system_metadata": { "app_name": "SEP-1 Abstraction AI", "proc_id": "3023" }, "model_instance": { "model_id": "Llama-3.1-8B-Instruct", "model_version": "2024-07-18" }, "user_identity": { "caller_type": "service", "caller_id": "sep1-pipeline" }, "target_identity": { "target_type": "patient", "target_id": "MRN-XXXXXXXX" }, "inputs": { "prompt": "Does the note contain an explicit mention that the patient has been discharged?" } }' ``` Reasoning traces, retrieved context, uncertainty estimates, and other intermediate artifacts are referenced back to the same `event_id`. This field is optional. ```bash theme={null} curl -X POST https://your-collector.example.org/event/internal-artifact \ -H "X-API-Key: $MEDLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_id": "9b1c...", "parent_event_id": "551b1676-1837-4278-988d-59ba3166b83e", "timestamp": "2026-01-10T05:31:20.110Z", "medlog_version": "0.0.1", "system_metadata": { "app_name": "SEP-1 Abstraction AI" }, "artifact": { "artifact_type": "reasoning_trace", "artifact_uri": "s3://medlog-artifacts/551b1676/cot.txt", "mime_type": "text/plain", "description": "Chain-of-thought for the discharge-disposition question" } }' ``` The prediction, generation, or recommendation shown to a clinician or patient. ```bash theme={null} curl -X POST https://your-collector.example.org/event/human-output \ -H "X-API-Key: $MEDLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_id": "a72f...", "parent_event_id": "551b1676-1837-4278-988d-59ba3166b83e", "timestamp": "2026-01-10T05:31:20.480Z", "medlog_version": "0.0.1", "system_metadata": { "app_name": "SEP-1 Abstraction AI" }, "output": { "output_type": "text", "output_uri": "s3://medlog-outputs/551b1676/answer.json", "summary": "Answer: N (no explicit discharge mention)" } }' ``` Outcomes and feedback often arrive later. Post them whenever they become observable, referencing the original `event_id`. ```bash theme={null} # A reviewer confirms the abstraction curl -X POST https://your-collector.example.org/event/outcome \ -H "X-API-Key: $MEDLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_id": "c0d3...", "parent_event_id": "551b1676-1837-4278-988d-59ba3166b83e", "timestamp": "2026-01-11T14:02:00Z", "medlog_version": "0.0.1", "system_metadata": { "app_name": "SEP-1 Abstraction AI" }, "outcome": { "outcome_type": "validated", "description": "QPS analyst: agree, case passes." } }' ``` ## Minimal implementations MedLog scales down. In low-resource or offline settings you can log only a small set of fields — [Header](/specification/header), [Model instance](/specification/model-instance), and [Outputs](/specification/outputs) — and add more fields as local capacity grows. When connectivity is intermittent, buffer events on-device with write-behind caching and synchronize once the network returns. See [low-resource settings](/implementation/low-resource). ## Next steps Understand the nine fields in depth. An annotated, real MedLog record showing every field. Wrap model calls at API gateways, LLM proxies, and agent frameworks. The five write-once event endpoints. # Example record Source: https://medlogprotocol.ai/specification/example-record An annotated, real MedLog record from the SEP-1 abstraction pilot in San Diego. This is a real (de-identified) MedLog record generated during the SEP-1 abstraction pilot at UC San Diego Health. It captures one LLM call within a multi-step sepsis quality-reporting workflow — note the shared `run_id` linking it to the other calls in the same abstraction run. ```json theme={null} { "header": { "medlog_version": "0.0.1", "event_id": "551b1676-1837-4278-988d-59ba3166b83e", "timestamp": "2026-01-10T05:31:19.805482+00:00", "system_info": "SEP-1 Abstraction AI", "run_id": "492dac48-dd7d-485e-8991-1325e814e73e" }, "model_instance": { "model_id": "Llama-3.1-8B-Instruct", "model_version": "2024-07-18" }, "user_identity": { "process_id": 3023 }, "target_identity": { "MRN": "XXXXXXXX", "CSN": "XXXXXXXX" }, "inputs": { "prompt": "You are a CMS quality abstractor. Your task is to review patient's medical note and answer the given sepsis compliance question following the abstraction instructions. Generate clear rationale to your answer by thinking step-by-step. [...] QUESTION: Does the note contain an explicit mention that the patient has already been discharged? Do not infer under any circumstances. [...]" }, "internal_artifacts": { "chain_of_thought": "The note does not explicitly mention that the patient has already been discharged. The note only mentions that the patient left the ICU at 0000, which implies they were transferred to another location, but does not confirm discharge.", "extracts": [ "Pt left ICU at 0000" ] }, "outputs": { "option": "N" }, "outcomes": { "category": "E - In-Numerator Population" }, "user_feedback": { "qps_analyst": "Agree, case passes." } } ``` ## Field-by-field The [Header](/specification/header): the protocol version, a stable `event_id`, the invocation `timestamp`, system info, and a `run_id` that links this call to the other LLM calls in the same SEP-1 abstraction run. The [Model instance](/specification/model-instance): `Llama-3.1-8B-Instruct`, version `2024-07-18`. The [User identity](/specification/user-identity). Here the caller is an automated process (`process_id: 3023`) — the abstraction pipeline, not a human. The [Target identity](/specification/target-identity): the patient, referenced by de-identified EHR identifiers (`MRN`, `CSN`). The [Inputs](/specification/inputs): the full prompt, including the abstraction instructions and the specific SEP-1 compliance question posed to the model. The [Internal artifacts](/specification/internal-artifacts): the model's chain-of-thought and the supporting `extracts` it pulled from the note. Trace-level analysis of this field is what revealed the model's confusion between intra-hospital transfers and true discharges. The [Output](/specification/outputs) shown downstream: the answer `N` to the discharge question. The [Outcome](/specification/outcomes): the resulting SEP-1 population category for this case. The [User feedback](/specification/user-feedback): the quality-and-patient-safety (QPS) analyst's adjudication — "Agree, case passes." This record uses the protocol's conceptual field names. The [API reference](/api-reference/overview) defines the concrete event payloads a collector accepts (for example, `system_metadata`, `caller_type`/`caller_id`, and the typed `artifact` / `output` / `outcome` objects). The conceptual model and the wire format describe the same nine fields. # Header Source: https://medlogprotocol.ai/specification/header Provenance information, execution context, and system metadata available at inference time. The MedLog record header consists of provenance information, execution context, and system metadata available at inference time, including server identifiers, timestamps of model invocation and input retrieval, and a stable event identifier for the newly-created MedLog record. Akin to `PROCID` in `syslog`, this field may also optionally include identifiers for run- or episode-level linkage (e.g., `run_id`, `parent_event_id`). These identifiers allow grouping events across multi-stage or agentic workflows without imposing a specific orchestration architecture. Lastly, to ensure interoperability, the header must include the version of the MedLog protocol specification that the record complies with. | Field | Type | Notes | | ----------------- | --------- | -------------------------------------------------------------- | | `event_id` | uuid | Stable identifier for this invocation. **Required.** | | `run_id` | uuid | Constant across all events in the same run. Optional. | | `parent_event_id` | uuid | The event this one expands on. Optional. | | `timestamp` | date-time | When the event occurred. **Required.** | | `medlog_version` | string | The protocol version the record complies with. **Required.** | | `system_metadata` | object | `hostname`, `app_name`, `proc_id`, `latency_ms`. **Required.** | # Inputs Source: https://medlogprotocol.ai/specification/inputs The input data provided to the model. The input data provided to the model. For structured predictive models, this includes feature vectors or structured fields. For generative models such as LLMs, it should include prompts, instructions, and any relevant environmental variables. When inputs are too large to log directly, such as imaging or genomic data, stable identifiers sufficient to retrieve the input data retrospectively should be recorded. | Field | Type | Notes | | ----------- | ------ | ------------------------------------------------ | | `prompt` | string | The prompt or instruction provided to the model. | | `input_uri` | uri | Pointer to bulky input data stored elsewhere. | # Internal artifacts Source: https://medlogprotocol.ai/specification/internal-artifacts Artifacts generated during inference for technical researchers and MLOps engineers. Artifacts generated during inference for technical researchers and MLOps engineers. This field may include: * **reasoning traces**, such as chain-of-thought, tree-of-thought, or graph-of-thought prompting paths; * **context retrieved** during retrieval-augmented generation; * **agent interaction traces**, such as iterative hypothesis testing or round-table discussions among AI agents; * **uncertainty estimates**, such as confidence scores, prediction intervals, generation quality metrics, or entropy-based measures; and * **interpretability artifacts**, including attribution maps, feature-importance scores, or saliency maps. For models that update continuously or episodically, including self-evolving models or agents with Bayesian updating, persistent memory, lifelong learning, or dynamic routing or reconfiguration, this field may also record relevant model states or memory snapshots. These records allow retrospective reconstruction of the model configuration at the time of use with greater detail than using only the version identifier from the [Model instance](/specification/model-instance) field. | Field | Type | Notes | | --------------- | ------ | ------------------------------------------------------------------------ | | `artifact_type` | enum | `text_chunk`, `reasoning_trace`, `tool_call`, `explanation`, or `other`. | | `artifact_uri` | uri | Pointer to the stored artifact. | | `mime_type` | string | Media type of the artifact. | | `description` | string | Human-readable description. | # Model instance Source: https://medlogprotocol.ai/specification/model-instance Stable identifiers of the AI model and version, with references to its model card and data sheet. Stable identifiers of the AI model and version, with references to its model card and data sheet. In the absence of a data sheet, the entry should record the version of the training data and any databases queried for retrieval-augmented generation or other knowledge injection methods. Any test-time edits to the model should also be recorded. | Field | Type | Notes | | ---------------- | ------ | ------------------------------------------------------ | | `model_id` | string | Stable model identifier, e.g. `Llama-3.1-8B-Instruct`. | | `model_version` | string | Model version, e.g. `2024-07-18`. | | `model_card_url` | uri | Reference to the model card. | | `data_sheet_url` | uri | Reference to the data sheet. | # Outcomes Source: https://medlogprotocol.ai/specification/outcomes Records of clinical actions or patient outcomes linked to the model recommendation. When feasible, records of clinical actions or patient outcomes linked to the model recommendation, for example, whether a suggested therapy was administered and the observed clinical result. Capturing outcomes faces three constraints: the link between recommendation and action is often indirect, outcomes may become observable only after a substantial delay, and relevant data may reside outside the immediate AI workflow. Even when outcome data are incomplete, partial linkage remains valuable for post-deployment surveillance, epidemiological analysis, and iterative model improvement. Outcomes may also include traces of how patients or clinicians interact with the EHR after viewing AI outputs, as recorded in EHR audit logs. Retrospective outcome data may be linked to the appropriate MedLog record identifier using provider attestations, temporal proximity, trial emulations, or other automated queries. This field may also record the strength of each linkage to support tiered evidence standards for outcome attribution. | Field | Type | Notes | | -------------- | --------- | ----------------------------------------------------- | | `outcome_type` | enum | `validated`, `contradicted`, `partial`, or `unknown`. | | `occurred_at` | date-time | When the outcome was observed. | | `description` | string | Description of the action or result. | | `evidence_uri` | uri | Pointer to supporting evidence. | # Patient- or clinician-facing outputs Source: https://medlogprotocol.ai/specification/outputs The outputs intended for human users. The outputs intended for human users, including: * **predictive outputs** such as labels, risk scores, or forecasts, with associated confidence measures; * **generative outputs** such as text, images, or videos; * **explanations or rationales** distilled from internal artifacts; and * **recommendations** generated by single or multi-agent systems. Any explainability or reasoning components presented to users should also be recorded in this field, as well as any triage levels or risk scores that determine if a MedLog record is flagged for human review. | Field | Type | Notes | | ------------- | ------ | ---------------------------------------------- | | `output_type` | enum | `text`, `image`, `video`, `audio`, or `other`. | | `output_uri` | uri | Pointer to the stored output. | | `summary` | string | Short human-readable summary of the output. | # Record schema overview Source: https://medlogprotocol.ai/specification/overview Each MedLog record corresponds to one model invocation and contains nine fields. The MedLog protocol captures AI use at the level of an inference call. It applies to simple "prompt to model to response" systems as well as multi-stage workflows that use retrieval, tools, rubric-based evaluation, or agentic orchestration. MedLog treats each model invocation as an event and allows events to be linked within the same run or episode. Each MedLog record corresponds to **one model invocation** and contains the following nine fields. ## Fields available at invocation Provenance information, execution context, and system metadata available at inference time. Stable identifiers of the AI model and version, with references to its model card and data sheet. The technical process, service, or workflow that invokes the model call. A reference to the entity about which the model produces output. The input data provided to the model. ## Fields appended later Artifacts generated during inference for technical researchers and MLOps engineers. The outputs intended for human users. Records of clinical actions or patient outcomes linked to the model recommendation. Any feedback provided by users, whether structured ratings or free-text comments. This documentation describes the conceptual nine-field model from the MedLog protocol. The [API reference](/api-reference/overview) defines the concrete event payloads a collector accepts. See the [annotated example record](/specification/example-record) for how the two relate. # Target identity Source: https://medlogprotocol.ai/specification/target-identity A reference to the entity about which the model produces output. When applicable, a reference to the entity about which the model produces output. For example, a patient ID number for clinical predictions or a claim ID for administrative tasks. Some models may not produce outputs about discrete targets, making this field optional. | Field | Type | Notes | | ------------- | ------ | ------------------------------------------ | | `target_type` | enum | `patient`, `document`, `claim`, or `none`. | | `target_id` | string | Identifier of the target entity. | # User feedback Source: https://medlogprotocol.ai/specification/user-feedback Any feedback provided by users, whether structured ratings or free-text comments. Any feedback provided by users, whether structured ratings or free-text comments, should be recorded to support model refinement and user experience improvements. | Field | Type | Notes | | --------------- | ------ | ---------------------------------------- | | `feedback_type` | enum | `rating`, `thumbs`, `text`, or `survey`. | | `rating_value` | number | A rating from 0 to 5. | | `comment` | string | Free-text comment. | # User identity Source: https://medlogprotocol.ai/specification/user-identity The technical process, service, or workflow that invokes the model call. The technical process, service, or workflow that invokes the model call. At a minimum, the identifier of the immediate calling process must be logged. When possible, the upstream users who initiated the call should also be recorded as a provenance chain. Human users, such as clinicians or patients, should be identified by their electronic health record (EHR) identifiers, such as National Provider Identifier (NPI) or medical record number (MRN). Users can also be algorithms or automated systems, such as AI agents or scheduled jobs that automatically trigger models for tasks such as risk calculation or triage. The level of user detail may vary across clinical settings, and it may be easier to attribute model use to a single clinician in outpatient care compared to inpatient teams. | Field | Type | Notes | | ------------- | ------ | ------------------------------------------------------- | | `caller_type` | enum | `clinician`, `patient`, `admin`, or `service`. | | `caller_id` | string | Identifier of the caller (e.g. NPI, MRN, service name). | # Team Source: https://medlogprotocol.ai/team MedLog is developed by a global team across 51 institutions and 11 countries.
Project lead Co-second author Deployment lead Corresponding author
Ayush Noori
Ayush Noori
University of Oxford
Aaron E. Boussina
Aaron E. Boussina
UC San Diego
Hai Ho Bich
Hai Ho Bich
Oxford University Clinical Research Unit
James Anibal
James Anibal
University of Oxford
Julia Maslinski
Julia Maslinski
Icahn School of Medicine at Mount Sinai
Manuel Burger
Manuel Burger
ETH Zurich
Martin Faltys
Martin Faltys
University of Bern
Adam Rodman
Adam Rodman
Beth Israel Deaconess Medical Center
Alan Karthikesalingam
Alan Karthikesalingam
Google DeepMind
Alessandro Blasimme
Alessandro Blasimme
ETH Zurich
Annelia Itwaru
Annelia Itwaru
Icahn School of Medicine at Mount Sinai
Ben Kaplan
Ben Kaplan
Icahn School of Medicine at Mount Sinai
Bilal A. Mateen
Bilal A. Mateen
University of Birmingham
Christopher A. Longhurst
Christopher A. Longhurst
UC San Diego
Daniel Yang
Daniel Yang
Kaiser Foundation Health and Hospitals
Dave deBronkart
Dave deBronkart
e-Patient Dave
Effy Vayena
Effy Vayena
ETH Zurich
Fedor Sergeev
Fedor Sergeev
ETH Zurich
Gauden Galea
Gauden Galea
World Health Organization
Ha Thi Hai Duong
Ha Thi Hai Duong
Oxford University Clinical Research Unit
Harold F. Wolf III
Harold F. Wolf III
HIMSS
Jacob Waxman
Jacob Waxman
Clalit Research Institute
Joerg C. Schefold
Joerg C. Schefold
University of Bern
Joshua C. Mandel
Joshua C. Mandel
Harvard Medical School
Juliana Rotich
Juliana Rotich
Gates Foundation
Kenneth D. Mandl
Kenneth D. Mandl
Harvard Medical School
Lily Poursoltan
Lily Poursoltan
UC San Diego Health
Maryam Mustafa
Maryam Mustafa
Lahore University of Management Sciences
Melissa Miles
Melissa Miles
Gates Foundation
Nigam H. Shah
Nigam H. Shah
Stanford Healthcare
Noa Dagan
Noa Dagan
Clalit Research Institute
Pavan Bodanki
Pavan Bodanki
Icahn School of Medicine at Mount Sinai
Peter Lee
Peter Lee
Microsoft Research
Philipp Koralus
Philipp Koralus
University of Oxford
Prathamesh Parchure
Prathamesh Parchure
Icahn School of Medicine at Mount Sinai
Prem Timsina
Prem Timsina
Icahn School of Medicine at Mount Sinai
Ran D. Balicer
Ran D. Balicer
Clalit Research Institute
Robert Korom
Robert Korom
Penda Health
Scott Mahoney
Scott Mahoney
Gates Foundation
Seth Hain
Seth Hain
Epic Systems
Tien Yin Wong
Tien Yin Wong
Tsinghua University
Trevor Mundel
Trevor Mundel
Gates Foundation
Vivek Natarajan
Vivek Natarajan
Google DeepMind
Ankit Sakhuja
Ankit Sakhuja
Icahn School of Medicine at Mount Sinai
Benjamin Glicksberg
Benjamin Glicksberg
Icahn School of Medicine at Mount Sinai
C. Louise Thwaites
C. Louise Thwaites
Oxford University Clinical Research Unit
Gunnar Rätsch
Gunnar Rätsch
Icahn School of Medicine at Mount Sinai
Karandeep Singh
Karandeep Singh
UC San Diego
David A. Clifton
David A. Clifton
University of Oxford
Isaac S. Kohane
Isaac S. Kohane
Harvard Medical School
Marinka Zitnik
Marinka Zitnik
Harvard Medical School