> ## 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. This helps clinicians save time, easily scan patient information, and get prepared for the visit.

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 summaries 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. Pick the one that matches where the clinician is working and what they need:

<CardGroup cols={2}>
  <Card title="Full Patient Summary" icon="file-lines">
    **What you get:**

    * Visit context, recent history, previous visits, and active problems
    * All sections returned together for chart review or patient-profile display

    **When to call and use this path:**

    * Call the API after generation status is `COMPLETED`.
    * Use this path for patient chart review, appointment detail screens, and patient-profile display.
    * Use this path when a clinician selects a patient from the schedule and needs the full overview.
  </Card>

  <Card title="Pre-Visit Summary" icon="calendar">
    **What you get:**

    * A compact pre-visit section only
    * The same generated summary, so you do not run generation again

    **When to call and use this path:**

    * Call the API after generation status is `COMPLETED`.
    * Use this path for schedule lists, appointment cards, and morning preview panels.
    * Use this path when you need a quick preview before the clinician opens the full chart.
  </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>

## Available cookbooks

<div className="hp-io-method-grid tut-hub-card-grid" data-cookbook-related-grid>
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/poll-patient-summary-status-before-retrieve">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Patient Summary</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--api">API</span>
      </div>

      <h3 className="hp-io-method-card-title">Poll Patient Summary Status Before Retrieve</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Poll until status is COMPLETED.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>
</div>

## 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.