Several documents

Send documents instead of document to summarize up to 50 documents about one patient as one summary. Statements in the summary cite the documents they came from.

{
  "documents": [
    {"id": "admission", "text": "…", "chart_date": "2026-09-01"},
    {"id": "echo", "text": "…", "chart_date": "2026-09-02",
     "subject": {"name": "…", "dob": "1950-02-03", "mrn": "…"}},
    {"text": "…"}
  ],
  "patient": {"dob": "1950-02-03"},
  "prompt": "Summarize this admission for the patient's GP."
}

documents cannot be combined with document, but can be combined with prep_documents and nlp_results.

Dates and order

Documents with a chart_date are read most recent first, and the summary is instructed to give the more recent one precedence where documents disagree. Documents without a date are treated as the oldest. Send dates whenever you have them: without them, the summary cannot tell an old problem from a current one.

Citations

Each statement in the summary cites its documents as [n], and references maps each number to a document id:

"summary": "Admitted with chest pain [1]; echo showed an ejection fraction of 55% [2] …",
"references": [{"ref": 1, "document": "admission"},
               {"ref": 2, "document": "echo"}]

references lists the documents the summary actually cites. A citation that matches none of your documents is removed, and the result carries a citations_unresolved warning. A document is always cited as a whole.

To show citations as links or chips, render the Markdown safely first and then replace [n] in the rendered text — see Result format.

One patient per job

A job should hold one patient’s documents, and the API checks that it does: it looks at the patient details you give (subject, patient) and at the documents themselves. When the documents appear to concern more than one patient, the summary is still written, and the result carries a warning naming the documents that seem to concern a different patient:

"warnings": [{"code": "possible_patient_mismatch",
              "message": "the documents may not all concern the same patient",
              "documents": ["echo"], "fields": ["dob"]}]

fields gives the kinds of patient detail that disagree (for example name or dob); the values themselves are never returned. Show this warning to the user before they rely on the summary: a summary of documents about different people can mix their histories.

Patient details you give help the check, so send them when you have them. If some documents could not be checked, the result says so with patient_check_incomplete, naming them.

The check adds a few seconds to a job with several documents. If you have already confirmed that the documents belong to one patient, you can set "options": {"check_patient": false} to skip the part that reads the documents; details you give are still checked.

Progress and timing

A job with several documents takes longer than one with a single document: about half a minute for a dozen short documents, and minutes for large jobs. While it runs, its status shows progress:

"progress": {"stage": "summarizing", "done": 0, "total": 3}

stage is reading or summarizing, for showing progress; done and total count within the stage, and total is 0 when it is not known in advance. Poll every two or three seconds.

Billing

A job is billed by its total text: every document plus the prompt in, and the summary out. See Limits and billing.