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

# Retrieve Patient Summaries

> Learn when a Patient Summary is available, how to retrieve full and pre-visit summaries, and how to handle empty clinical states in your UI

After a generation job reaches the `COMPLETED` status, your application can retrieve the generated Patient Summary and display it in schedule, chart, or patient views.

Generation and retrieval are separate operations. A successful generation request does not return the summary. Instead, wait for the job to complete, then retrieve either the full Patient Summary or the pre-visit section your application needs.
For request and response details, refer to the [Patient Summaries APIs](/patient-summary-api-reference/summaries).

Patient Summary supports two retrieval paths:

<CardGroup cols={2}>
  <Card title="Full Patient Summary" icon="file-lines">
    Retrieve the complete summary for chart review or patient-profile display.
  </Card>

  <Card title="Pre-Visit Summary" icon="calendar">
    Retrieve the pre-visit section for schedule lists and short previews.
  </Card>
</CardGroup>

Your application is responsible for:

* Confirming the generation job completed successfully.
* Choosing the full summary or the pre-visit section.
* Mapping summary sections into your UI.
* Handling missing appointments and limited clinical history clearly.

Before retrieving a summary:

<Steps>
  <Step title="Confirm Generation Completed">
    Poll the [Summary Jobs APIs](/patient-summary-api-reference/summary-jobs) until status is `COMPLETED`. Do not treat job output as final before then.
  </Step>

  <Step title="Choose What to Display">
    Decide whether the clinician needs the full summary or a short pre-visit preview.
  </Step>

  <Step title="Choose How to Look It Up">
    Retrieve by `patient_summary_id`, or by `fhir_encounter_id` and `fhir_practitioner_id` when your workflow stores partner identifiers.
  </Step>

  <Step title="Handle Empty States">
    Design UI for no upcoming appointment and limited prior history before you render the summary.
  </Step>
</Steps>

<Tip>
  Retrieve summaries only after status is `COMPLETED`. If the clinician opens a patient chart while generation is still running, show a preparing state, then retrieve the summary when the job finishes.
</Tip>

## Decide on a retrieval path

Choose the retrieval path based on what your UI needs and which identifiers you store.

<AccordionGroup>
  <Accordion title="Full Patient Summary">
    Use the full Patient Summary when a clinician needs the complete pre-visit overview.

    Typical scenarios include:

    * Patient chart review.
    * Appointment detail screens.
    * Deep clinical review before the visit.

    Look up the summary by:

    * `patient_summary_id`, or
    * `fhir_encounter_id` and `fhir_practitioner_id`.

    Refer to [Patient Summary by ID](/patient-summary-api-reference/summaries/patient-summary) and [Patient Summary by partner identifiers](/patient-summary-api-reference/summaries/encounter-practitioner).
  </Accordion>

  <Accordion title="Pre-Visit Summary">
    Use the pre-visit section when your UI needs a short preview instead of the full object.

    Typical scenarios include:

    * Provider schedule lists.
    * Appointment cards.
    * Morning preview panels.

    Look up the pre-visit section by:

    * `patient_summary_id`, or
    * `fhir_encounter_id` and `fhir_practitioner_id`.

    Refer to [Pre-visit summary by ID](/patient-summary-api-reference/summaries/pre-visit-summary) and [Pre-visit summary by partner identifiers](/patient-summary-api-reference/summaries/encounter-pre-visit).
  </Accordion>
</AccordionGroup>

| Scenario                                    | Recommended retrieval                           |
| :------------------------------------------ | :---------------------------------------------- |
| Schedule preview                            | Pre-visit summary                               |
| Appointment card                            | Pre-visit summary                               |
| Patient chart review                        | Full Patient Summary                            |
| Partner IDs already stored in your EHR      | Full or pre-visit by encounter and practitioner |
| `patient_summary_id` stored from generation | Full or pre-visit by Patient Summary ID         |

## Typical retrieval workflow

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart LR
  A["Generation complete"] --> B["Confirm status"]
  B --> C["Retrieve summary"]
  C --> D["Map sections"]
  D --> E["Display in UI"]

  style A fill:#FFF394,stroke:#333,color:#000
  style B fill:#FFF394,stroke:#333,color:#000
  style C fill:#FFF394,stroke:#333,color:#000
  style D fill:#FFF394,stroke:#333,color:#000
  style E fill:#FFF394,stroke:#333,color:#000
```

<Steps>
  <Step title="Confirm Job Status">
    Check generation status with the [Summary Jobs APIs](/patient-summary-api-reference/summary-jobs) using `patient_summary_id`, or `fhir_encounter_id` and `fhir_practitioner_id`.
  </Step>

  <Step title="Stop on Terminal Status">
    Continue only when status is `COMPLETED`. For `FAILED` or `ABORTED`, log identifiers and show a clear UI fallback.
  </Step>

  <Step title="Retrieve the Content">
    Call the full summary or pre-visit endpoint that matches your identifiers.
  </Step>

  <Step title="Render the Sections">
    Map the returned sections into your schedule, chart, or patient-profile UI.
  </Step>
</Steps>

## Understanding summary sections

A completed Patient Summary typically contains the following sections:

| Section              | Description                                                |
| :------------------- | :--------------------------------------------------------- |
| **About this visit** | Appointment type and reason for the visit.                 |
| **Summary**          | A brief overview of the patient's recent clinical history. |
| **Previous visits**  | Short summaries of recent encounters.                      |
| **Problems**         | Active problem list.                                       |

### Example response

The following example shows the shape of a successful retrieve response from the Patient Summaries APIs:

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "patient_summary": {
    "sections": [
      {
        "contents": [
          {
            "problem": {
              "description": "Asthma"
            },
            "text": "Patient presents with shortness of breath.",
            "visit": {
              "date": "2026-05-22T10:00:00Z",
              "description": "Follow-up for asthma"
            }
          }
        ],
        "section_type": "ABOUT_VISIT",
        "snippet_index": 0,
        "title": "About Visit"
      }
    ],
    "updated_at": "2026-05-22T10:00:00Z"
  }
}
```

Each section in the response includes:

* `section_type` - Section identifier, such as `ABOUT_VISIT`.
* `title` - Display title for the section.
* `snippet_index` - Index of the section snippet.
* `contents` - Array of content objects that can include `text`, `problem`, and `visit` fields.

<Note>
  The sections returned depend on the clinical data available in CKG and your implementation requirements. Historical lookback and summary length can vary by configuration.
</Note>

## Handle empty clinical states

Not every patient profile has the same data shape. Design empty states as first-class UI.

<AccordionGroup>
  <Accordion title="No Upcoming Appointment">
    **Cause:** The provider opens a patient profile, but the patient does not have an upcoming appointment for that day.

    **Resolution:** Show:

    `No upcoming appointment. Schedule an appointment to view the summary.`

    Do not imply that CKG ingestion failed or that generation failed when the patient is simply not on today's schedule.
  </Accordion>

  <Accordion title="Upcoming Appointment, No Prior Record">
    **Cause:** The patient has an upcoming appointment, but no previous encounter record was found in CKG.

    **Resolution:**

    * Show **About this visit**.
    * Show **Problems** when available.
    * Under **Summary**, show that no record was found.
    * Under **Previous visits**, show that no record was found.
  </Accordion>

  <Accordion title="Upcoming Appointment with Prior Records">
    **Cause:** Appointment context and prior clinical history are available in CKG.

    **Resolution:** Display all four sections. Keep the reading experience short and scannable. Emphasize **About this visit** and **Summary** first, then let clinicians move into **Previous visits** and **Problems**.
  </Accordion>

  <Accordion title="Generation Still Running">
    **Cause:** The clinician opened the patient chart before the generation job finished.

    **Resolution:** Show a preparing or loading state. Continue monitoring status, then retrieve and render the summary when status is `COMPLETED`.
  </Accordion>

  <Accordion title="Job Failed or Aborted">
    **Cause:** Generation reached `FAILED` or `ABORTED`.

    **Resolution:** Do not display incomplete content as a finished summary. Log the identifiers, offer retry if applicable, and fall back to manual chart review.
  </Accordion>
</AccordionGroup>

## Common workflows

<AccordionGroup>
  <Accordion title="Schedule Preview">
    * Generate summaries for scheduled appointments.
    * Poll until appointments reach `COMPLETED`.
    * Retrieve pre-visit summaries for the schedule list.
    * Open the full summary when the clinician selects a patient.
  </Accordion>

  <Accordion title="Patient Profile Review">
    * Confirm an upcoming appointment exists.
    * Check whether a summary already exists.
    * Generate if needed.
    * Retrieve the full summary and render all sections.
  </Accordion>

  <Accordion title="Progressive Readiness">
    * Trigger scheduled generation in the morning.
    * As each job completes, retrieve and cache that appointment's summary.
    * Show ready patients immediately while others remain in a preparing state.
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  * Retrieve content only after generation status is `COMPLETED`.
  * Prefer `fhir_encounter_id` and `fhir_practitioner_id` when those are already the keys in your EHR workflow.
  * Use the pre-visit section for dense schedule UIs, and the full summary for chart review.
  * Cache completed summaries for the appointment when appropriate, and avoid unnecessary regeneration.
  * Render empty states as first-class UI, not as missing components.
  * Keep the reading experience short and scannable.
  * Log the encounter, practitioner, `patient_summary_id`, and status that preceded retrieval failures.
</Tip>

## Next steps

Continue with the following guides:

* [Patient Summary best practices](/documentation/how-to/patient-summary/best-practices) for production polling, retries, logging, and security.
* [Patient Summary basic usage](/documentation/how-to/patient-summary/basic-usage) to follow an end-to-end integration example.
* [Patient Summaries APIs](/patient-summary-api-reference/summaries) to explore the full and pre-visit retrieval endpoints.