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

# Symptom reports

> Patient-reported symptoms, moods, and functional status assessments. 6 log types with payload schemas and examples.

Patient-reported symptoms, moods, and functional status assessments. Submit these via `POST /v1/logs/batch` or the [Python SDK](/reference/sdk); see [How logs work](/send-data/how-logs-work) for submission fields and the difference between **lifecycle-tracked** and point-in-time log types.

## Symptom report

**Type:** `symptom_report` · **Source:** Python SDK / REST · **Lifecycle-tracked** · **Extensible**

Reserved for structured symptom severity with a defined instrument: validated or standard instruments (esas\_r, pro\_ctcae, ctcae, custom) with symptom name and score per item; score 0 = resolved.

**Payload**

<ResponseField name="instrument" type="string" required>
  esas\_r | pro\_ctcae | ctcae | custom or clinic-defined string. Example: `esas_r`, `pro_ctcae`, `ctcae`
</ResponseField>

<ResponseField name="recall_period_days" type="integer">
  Reflects the instrument's own temporal scope. PRO-CTCAE = 7 days; ESAS-r = 0 (point-in-time). Do not set arbitrarily.
</ResponseField>

<ResponseField name="symptoms" type="object[]" required>
  <Expandable title="fields">
    <ResponseField name="name" type="string" required>
      Symptom name. For esas\_r must be one of: pain, tiredness, drowsiness, nausea, appetite, shortness\_of\_breath, depression, anxiety, wellbeing, constipation.
    </ResponseField>

    <ResponseField name="type" type="string">
      Symptom type classification; instrument-specific or free-text category.
    </ResponseField>

    <ResponseField name="score" type="number" required>
      Unified severity; 0 = resolved for all instruments. ESAS-r 0–10; PRO-CTCAE 0–4; CTCAE 0–5; custom 0–10. Scale auto-filled for known instruments.
    </ResponseField>

    <ResponseField name="scale_min" type="number">
      Auto-filled for esas\_r (0–10), pro\_ctcae (0–4), ctcae (0–5), custom (0–10). Supply only for clinic-defined instruments.
    </ResponseField>

    <ResponseField name="scale_max" type="number">
      Auto-filled for esas\_r (0–10), pro\_ctcae (0–4), ctcae (0–5), custom (0–10). Supply only for clinic-defined instruments.
    </ResponseField>

    <ResponseField name="frequency" type="integer">
      PRO-CTCAE-specific axes; omit for other instruments.
    </ResponseField>

    <ResponseField name="interference" type="integer">
      PRO-CTCAE-specific axes; omit for other instruments.
    </ResponseField>

    <ResponseField name="snomed_code" type="string">
      Preferred identity key for cross-instrument matching.
    </ResponseField>

    <ResponseField name="meddra_code" type="string">
      Secondary identity; used when snomed\_code is absent.
    </ResponseField>

    <ResponseField name="relatedness_to_treatment" type="string" />

    <ResponseField name="onset_date" type="string">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="resolution_date" type="string">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="resolution_status" type="string">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="action_taken" type="string">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="seriousness" type="string">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="requires_hospitalization" type="boolean">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="suspected_agent" type="string">
      Adverse event annotation; omit when not applicable.
    </ResponseField>

    <ResponseField name="extensions" type="object">
      Open key/value bag for client/source-specific fields that lack a typed slot; merged into the entry's extensions (leaf-level, last-writer-wins by event timestamp).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Accepts a legacy string (e.g. 'patient\_self\_report') or a structured Source object.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.SYMPTOM_REPORT,
      patient_id="your-patient-id",
      payload={
          "instrument": "esas_r",
          "symptoms": [...]
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "symptom_report",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "instrument": "esas_r",
          "symptoms": [...]
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`symptom_free_text`](/reference/log-types/symptom-reports#symptom-free-text) for free-text symptom descriptions, [`symptom_detail`](/reference/log-types/symptom-reports#symptom-detail) for follow-up detail on one symptom, [`mood_report`](/reference/log-types/symptom-reports#mood-report) for mood labels, [`health_metric`](/reference/log-types/symptom-reports#health-metric) for single scalar wellbeing/energy without instrument. instrument is required; scale\_min/scale\_max auto-filled for known instruments.
</Note>

## Mood report

**Type:** `mood_report` · **Source:** Python SDK / REST · **Lifecycle-tracked** · **Extensible**

Reserved for categorical mood or emotion labels: mood terms (e.g. anxious, hopeful, calm) with optional intensity 0-10; source (checkin, spontaneous, prompted) optional.

**Payload**

<ResponseField name="moods" type="object[]" required>
  <Expandable title="fields">
    <ResponseField name="mood" type="string" required>
      Categorical mood label.. Example: `anxious`, `hopeful`, `calm`
    </ResponseField>

    <ResponseField name="intensity" type="number | null">
      Optional 0-10; omit or null when not known.. Minimum: 0. Maximum: 10
    </ResponseField>

    <ResponseField name="extensions" type="object">
      Open key/value bag for client/source-specific fields that lack a typed slot; merged into the entry's extensions (leaf-level, last-writer-wins by event timestamp).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Accepts a legacy string (e.g. 'patient\_self\_report') or a structured Source object.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.MOOD_REPORT,
      patient_id="your-patient-id",
      payload={
          "moods": [...]
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "mood_report",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "moods": [...]
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`health_metric`](/reference/log-types/symptom-reports#health-metric) for numeric wellbeing/energy/pain scales without a mood label, [`symptom_report`](/reference/log-types/symptom-reports#symptom-report) for symptom severity, [`questionnaire_response`](/reference/log-types/questionnaires#questionnaire-response) for full questionnaire.
</Note>

## Symptom free text

**Type:** `symptom_free_text` · **Source:** Python SDK / REST

Reserved for unstructured symptom text to be processed by extraction: free-text symptom descriptions from conversation or direct input; feeds NLP to produce symptom\_report, symptom\_detail, mood\_report, etc.

**Payload**

<ResponseField name="text" type="string" required>
  Free-text symptom description as reported by the patient or captured from conversation.
</ResponseField>

<ResponseField name="associated_symptoms" type="object[]">
  <Expandable title="fields">
    <ResponseField name="name" type="string" required>
      Symptom display name or type.
    </ResponseField>

    <ResponseField name="snomed_code" type="string">
      SNOMED CT code; first choice for matching.
    </ResponseField>

    <ResponseField name="meddra_code" type="string">
      MedDRA code; used when snomed\_code unset.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Accepts a legacy string (e.g. 'patient\_self\_report') or a structured Source object.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.SYMPTOM_FREE_TEXT,
      patient_id="your-patient-id",
      payload={
          "text": "..."
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "symptom_free_text",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "text": "..."
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`symptom_report`](/reference/log-types/symptom-reports#symptom-report) for already-structured symptom scores, [`symptom_detail`](/reference/log-types/symptom-reports#symptom-detail) for follow-up detail on a known symptom. Not intended for structured lab or clinical data.
</Note>

## Symptom detail

**Type:** `symptom_detail` · **Source:** Python SDK / REST

Reserved for follow-up detail about an already-reported symptom: one detail (location, duration, character, trigger, recurrence status, etc.) linked to a prior symptom via symptom\_type/snomed\_code/meddra\_code; detail\_type + response.

**Payload**

<ResponseField name="symptom_type" type="string" required>
  Symptom type; used for matching when snomed\_code and meddra\_code unset.
</ResponseField>

<ResponseField name="snomed_code" type="string">
  SNOMED CT code; first choice for matching target symptom.
</ResponseField>

<ResponseField name="meddra_code" type="string">
  MedDRA code; used when snomed\_code unset.
</ResponseField>

<ResponseField name="detail_type" type="string" required>
  Category of detail (e.g. location, duration, character, trigger, alleviating\_factor, recurrence status, other). Client-extensible.. Example: `location`, `duration`, `character`
</ResponseField>

<ResponseField name="question" type="string">
  Optional — the question that prompted this detail response.
</ResponseField>

<ResponseField name="response" type="string" required>
  The patient's or clinician's answer to the detail question.
</ResponseField>

<ResponseField name="source" type="string | object">
  Who reported this detail. Accepts a legacy string or a structured Source object. Flows into the sources of the matched SymptomSimple.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.SYMPTOM_DETAIL,
      patient_id="your-patient-id",
      payload={
          "symptom_type": "...",
          "detail_type": "location",
          "response": "..."
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "symptom_detail",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "symptom_type": "...",
          "detail_type": "location",
          "response": "..."
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`symptom_report`](/reference/log-types/symptom-reports#symptom-report) for initial symptom report with score, [`symptom_free_text`](/reference/log-types/symptom-reports#symptom-free-text) for unstructured symptom text, [`questionnaire_item_response`](/reference/log-types/questionnaires#questionnaire-item-response) for standalone question and answer.
</Note>

## Functional class

**Type:** `functional_class` · **Source:** Python SDK / REST, Integration · **Extensible**

Reserved for functional status or performance class from standard instruments: NYHA, CCS, ECOG, Karnofsky, ADL, IADL with class/score; reported\_by (patient, clinician, caregiver).

**Payload**

<ResponseField name="instrument" type="string" required>
  Standard functional instrument name.. Example: `nyha`, `ccs`, `ecog`
</ResponseField>

<ResponseField name="class" type="integer" required>
  Numeric class or score. 1–4 for NYHA/CCS; 0–4 for ECOG; 0–100 for Karnofsky; ADL/IADL use item-based scoring.. Minimum: 0. Maximum: 100
</ResponseField>

<ResponseField name="reported_by" type="string">
  Who reported the functional class (e.g. patient, clinician, caregiver).. Example: `patient`, `clinician`, `caregiver`
</ResponseField>

<ResponseField name="change_from_prior" type="object">
  <Expandable title="fields">
    <ResponseField name="previous_class" type="integer">
      Prior class value for comparison.
    </ResponseField>

    <ResponseField name="date" type="string">
      Date of prior assessment.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="assessment_type" type="string">
  ECOG, Karnofsky, NYHA, ADL, IADL, other
</ResponseField>

<ResponseField name="narrative" type="string">
  Free-text clinical context or summary of functional status.
</ResponseField>

<ResponseField name="domain" type="string">
  Functional domain being assessed (e.g. physical, cognitive, social).. Example: `physical`, `cognitive`, `social`
</ResponseField>

<ResponseField name="assessor_type" type="string">
  Role of the person doing the assessment (e.g. clinician, patient, caregiver).. Example: `clinician`, `patient`, `caregiver`
</ResponseField>

<ResponseField name="score_scale" type="string">
  Scale definition when using a non-standard instrument.
</ResponseField>

<ResponseField name="baseline_comparison" type="string">
  Comparison note relative to a prior baseline.
</ResponseField>

<ResponseField name="functional_limitations" type="string[]">
  List of specific functional limitations identified (e.g. 'unable to climb stairs').
</ResponseField>

<ResponseField name="extensions" type="object">
  Open key/value bag for client/source-specific fields that lack a typed slot; merged into the entry's extensions (leaf-level, last-writer-wins by event timestamp).
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Legacy string or structured Source object.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.FUNCTIONAL_CLASS,
      patient_id="your-patient-id",
      payload={
          "instrument": "nyha",
          "class": 0
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "functional_class",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "instrument": "nyha",
          "class": 0
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`vitals_measurement`](/reference/log-types/lab-clinical#vitals-measurement) for vital signs, [`lab_results`](/reference/log-types/lab-clinical#lab-results) for lab results, [`clinical_measurement`](/reference/log-types/lab-clinical#clinical-measurement) for other clinical measurements like ejection fraction, [`symptom_report`](/reference/log-types/symptom-reports#symptom-report) for symptom severity.
</Note>

## Health metric

**Type:** `health_metric` · **Source:** Python SDK / REST, Integration · **Extensible**

Reserved for a single scalar patient-reported metric with an explicit scale: ad-hoc wellbeing, energy, pain NRS, appetite, hydration (metric\_type + score + scale\_min + scale\_max).

**Payload**

<ResponseField name="metric_type" type="string" required>
  e.g. wellbeing, energy, pain\_nrs, appetite, hydration or client-defined.
</ResponseField>

<ResponseField name="score" type="number" required>
  The measured value on the scale defined by scale\_min and scale\_max.
</ResponseField>

<ResponseField name="scale_min" type="number" required>
  Must always be provided explicitly; not inferred.
</ResponseField>

<ResponseField name="scale_max" type="number" required>
  Must always be provided explicitly; not inferred.
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Legacy string or structured Source object.
</ResponseField>

<ResponseField name="extensions" type="object">
  Open key/value bag for client/source-specific fields that lack a typed slot; merged into the entry's extensions (leaf-level, last-writer-wins by event timestamp).
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.HEALTH_METRIC,
      patient_id="your-patient-id",
      payload={
          "metric_type": "...",
          "score": 0,
          "scale_min": 0,
          "scale_max": 0
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "health_metric",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "metric_type": "...",
          "score": 0,
          "scale_min": 0,
          "scale_max": 0
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`mood_report`](/reference/log-types/symptom-reports#mood-report) for mood labels, [`questionnaire_response`](/reference/log-types/questionnaires#questionnaire-response) for full validated questionnaire, [`symptom_report`](/reference/log-types/symptom-reports#symptom-report) for symptom with instrument, [`questionnaire_item_response`](/reference/log-types/questionnaires#questionnaire-item-response) for single Q\&A with question text.
</Note>