> ## 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.
# Wait for Patient Summary before Fetch
> Poll Patient Summary job status until COMPLETED before calling retrieve APIs
export const CbRecipeMeta = ({items = []}) =>
;
};
}
sidebar={{
apiHref: "/patient-summary-api-reference/summary-jobs/encounter-status",
authSections: [
{
title: "Partner API",
text: "Authenticate every REST call with Partner Token headers on each request. See",
href: "/documentation/get-started/partner-authentication",
linkLabel: "Partner authentication",
scopes: ["sdp_suki_token", "sdp_provider_id"],
},
],
glance: [
{ label: "Product", value: "Patient Summary" },
{ label: "Surface", value: "Partner API" },
{ label: "Time", value: "~5 min" },
{ label: "Level", value: "Beginner" },
],
}}
>
## Problem
Retrieve APIs return empty or missing summaries right after you trigger generation. The job is still `READY` or `RUNNING`, so retrieve endpoints have nothing to return yet.
Patient Summary generation is asynchronous. Poll job status until `COMPLETED`, then call retrieve. Treat `FAILED` and `ABORTED` as terminal so your loop exits cleanly.
## Architecture
```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFFBDE','primaryTextColor':'#1C1C1C','primaryBorderColor':'#FFD147','lineColor':'#6F5410','secondaryColor':'#FFFDF5','tertiaryColor':'#FFEB94','fontSize':'13px'}}}%%
flowchart LR
A[Generate summary] --> B[Poll status]
B --> C{Status}
C -->|COMPLETED| D[Retrieve]
C -->|FAILED / ABORTED| E[Stop]
C -->|READY / RUNNING| B
```
## Prerequisites
Triggered generation for the encounter and stored `patient_summary_id`. See [Generate a Patient Summary](/documentation/cookbooks/generate-patient-summary-for-encounter).Completed [Partner onboarding](/documentation/get-started/partner-onboarding) with `sdp_suki_token` and `sdp_provider_id` headers ready.The same `fhir_encounter_id` and `fhir_practitioner_id` values you used to generate.
## Solution
[Generate a Patient Summary](/documentation/cookbooks/generate-patient-summary-for-encounter)
Poll until `COMPLETED`, or stop on `FAILED` / `ABORTED`.
Retrieve the summary by FHIR ids (or by `patient_summary_id` if you stored it).
Poll [Get patient summary generation status for encounter](/patient-summary-api-reference/summary-jobs/encounter-status) until `COMPLETED`, then retrieve. Treat `FAILED` and `ABORTED` as terminal. You can also poll by `patient_summary_id` with [Get patient summary job status](/patient-summary-api-reference/summary-jobs/job-status).
```typescript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
// poll-patient-summary-status-before-retrieve.ts
const BASE_URL = process.env.SUKI_BASE_URL ?? "https://sdp.suki.ai";
const SDP_SUKI_TOKEN = process.env.SDP_SUKI_TOKEN!;
const SDP_PROVIDER_ID = process.env.SDP_PROVIDER_ID ?? "";
const FHIR_ENCOUNTER_ID = process.env.FHIR_ENCOUNTER_ID ?? "enc-123";
const FHIR_PRACTITIONER_ID = process.env.FHIR_PRACTITIONER_ID ?? "pract-456";
function restHeaders(): Record {
const headers: Record = { sdp_suki_token: SDP_SUKI_TOKEN };
if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;
return headers;
}
async function waitUntilCompleted(
fhirEncounterId: string,
fhirPractitionerId: string,
pollMs = 2000,
maxAttempts = 60
): Promise {
for (let i = 0; i < maxAttempts; i++) {
const res = await fetch(
`${BASE_URL}/api/v1/patient-summary/encounter/${fhirEncounterId}/practitioner/${fhirPractitionerId}/status`,
{ headers: restHeaders() }
);
if (!res.ok) {
throw new Error(`Get patient summary status failed: ${res.status}`);
}
const { status } = (await res.json()) as { status: string };
if (status === "COMPLETED") return "COMPLETED";
if (status === "FAILED" || status === "ABORTED") return status;
await new Promise((r) => setTimeout(r, pollMs));
}
throw new Error("Timed out waiting for patient summary status");
}
async function retrievePatientSummary(
fhirEncounterId: string,
fhirPractitionerId: string
): Promise {
const res = await fetch(
`${BASE_URL}/api/v1/patient-summary/encounter/${fhirEncounterId}/practitioner/${fhirPractitionerId}`,
{ headers: restHeaders() }
);
if (!res.ok) {
throw new Error(`Retrieve patient summary failed: ${res.status}`);
}
return res.json();
}
const outcome = await waitUntilCompleted(FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID);
if (outcome === "COMPLETED") {
const summary = await retrievePatientSummary(
FHIR_ENCOUNTER_ID,
FHIR_PRACTITIONER_ID
);
console.log(JSON.stringify(summary, null, 2));
} else {
console.error("Terminal status:", outcome);
}
```
```python theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
# poll_patient_summary_status_before_retrieve.py
# pip install requests
import json
import os
import time
import requests
BASE_URL = os.environ.get("SUKI_BASE_URL", "https://sdp.suki.ai")
SDP_SUKI_TOKEN = os.environ["SDP_SUKI_TOKEN"]
SDP_PROVIDER_ID = os.environ.get("SDP_PROVIDER_ID", "")
FHIR_ENCOUNTER_ID = os.environ.get("FHIR_ENCOUNTER_ID", "enc-123")
FHIR_PRACTITIONER_ID = os.environ.get("FHIR_PRACTITIONER_ID", "pract-456")
def rest_headers() -> dict[str, str]:
headers = {"sdp_suki_token": SDP_SUKI_TOKEN}
if SDP_PROVIDER_ID:
headers["sdp_provider_id"] = SDP_PROVIDER_ID
return headers
def wait_until_completed(
fhir_encounter_id: str,
fhir_practitioner_id: str,
poll_s: float = 2.0,
max_attempts: int = 60,
) -> str:
for _ in range(max_attempts):
res = requests.get(
f"{BASE_URL}/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}/status",
headers=rest_headers(),
timeout=30,
)
res.raise_for_status()
status = res.json().get("status")
if status == "COMPLETED":
return "COMPLETED"
if status in ("FAILED", "ABORTED"):
return status
time.sleep(poll_s)
raise TimeoutError("Timed out waiting for patient summary status")
def retrieve_patient_summary(fhir_encounter_id: str, fhir_practitioner_id: str):
res = requests.get(
f"{BASE_URL}/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}",
headers=rest_headers(),
timeout=30,
)
res.raise_for_status()
return res.json()
outcome = wait_until_completed(FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID)
if outcome == "COMPLETED":
summary = retrieve_patient_summary(FHIR_ENCOUNTER_ID, FHIR_PRACTITIONER_ID)
print(json.dumps(summary, indent=2))
else:
print("Terminal status:", outcome)
```
Call [Get patient summary generation status for encounter](/patient-summary-api-reference/summary-jobs/encounter-status) with the same `fhir_encounter_id` and `fhir_practitioner_id` you used to generate.
Retry every few seconds while status is `READY` or `RUNNING`. Exit the loop when status is `COMPLETED`, `FAILED`, or `ABORTED`.
Alternatively, poll [Get patient summary job status](/patient-summary-api-reference/summary-jobs/job-status) with the stored `patient_summary_id`.
Only after `COMPLETED`, call retrieve Patient Summary APIs for the encounter or job.
## Try it
* **Status progresses to COMPLETED**
After generate, polling should move from `READY` or `RUNNING` to `COMPLETED`. Retrieve only after that transition.
* **Terminal failures exit the loop**
`FAILED` and `ABORTED` should stop polling. Do not call retrieve for those outcomes.
* **Matching IDs across generate and poll**
Using different encounter or practitioner IDs than generate returns the wrong job or a 404.
## Common mistakes
* Calling retrieve while status is still `READY` or `RUNNING`.
* Stopping only on `COMPLETED` and ignoring `FAILED` / `ABORTED` (those loops never end cleanly).
* Polling with different encounter or practitioner IDs than you used to generate.
## Related cookbooks
Trigger generation and save the ID.
Upload FHIR, then wait for COMPLETED.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.