> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emtelligent.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server. # Generating a cohort A cohort is up to 50 patients generated from one description of a population. The patients live in one fictional regional health system, created for the cohort: its hospitals, clinics and clinicians are shared, so patients see the same doctors and are admitted to the same hospitals, as in a real health system's records. Send `POST /v1/cohorts`: ```json { "size": 20, "age": {"min": 45, "max": 85}, "female_proportion": 0.5, "complexity": {"min": 3, "max": 8}, "conditions": [ {"name": "type 2 diabetes mellitus", "proportion": 0.3}, {"name": "essential hypertension", "proportion": 0.5} ], "documents_per_patient": {"min": 3, "max": 6}, "country": "US", "region": "Ohio", "outputs": ["fhir", "notes", "bulk"], "seed": 7 } ``` ## The specification | Field | Default | | | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `size` | (required) | Patients, 1 to 50 | | `age` | 18 to 90 | Each patient's age is chosen in this range | | `female_proportion` | `0.5` | The share of women | | `complexity` | 1 to 10 | Each patient's [complexity](/synth/guides/patients#complexity) is chosen in this range | | `conditions` | none | Conditions given to an exact share of the patients (rounded): with `size` 20, a proportion of `0.3` gives exactly 6 patients the condition. Other patients may still have it, as it arises naturally | | `documents_per_patient` | 3 to 8 | Each patient's document count is chosen in this range, at most 50 | | `document_types` | all | As for [a patient](/synth/guides/patients#documents) | | `timeline` | ends today | As for [a patient](/synth/guides/patients#timeline) | | `country`, `region` | random | Where the health system is: `US` or `CA`, and a state or province by name or abbreviation | | `outputs` | `["fhir", "notes"]` | Each patient's `fhir`, `notes` and `pdf`, and `bulk` for the whole cohort as FHIR Bulk Data | | `seed` | random | The same specification and seed give the same patients' ages, sexes, complexities, document counts and assigned conditions | ## Progress Poll `GET /v1/cohorts/{cohort_id}`. Its `progress` counts the patients by status while they are generated, in parallel: ```json { "id": "…", "status": "running", "size": 20, "max_documents": 120, "progress": { "queued": 9, "running": 3, "succeeded": 8, "failed": 0, "canceled": 0 }, … } ``` A cohort of 20 patients usually takes well under an hour. When every patient has finished, the cohort's results are packaged and its status becomes `succeeded`. ## Results | `name` | File | | | ---------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `patients` | `cohort_patients.zip` | A folder per patient, `001_/` and so on, with `fhir_bundle.json`, `result.json`, and `notes/` and `pdf/` as requested; and `manifest.json` listing each patient's folder, status and document count | | `bulk` | `cohort_fhir_bulk.zip` | The whole cohort as [FHIR Bulk Data](https://hl7.org/fhir/uv/bulkdata/): one NDJSON file per resource type and a `manifest.json` | | `result` | `cohort.json` | The health system (its facilities and clinicians), each patient's status, and the condition counts below | Download each from `GET /v1/cohorts/{cohort_id}/results/{name}`, **once**, within 24 hours. See [Results](/synth/guides/results#bulk-data) for the Bulk Data format. ## Summary A succeeded cohort's `summary` says what was delivered, and counts the patients with each condition: ```json "summary": { "patients": 20, "succeeded": 20, "failed": 0, "canceled": 0, "documents": 91, "failures": [], "health_system": { "region": "Ohio", "country": "US", "facilities": 9, "clinicians": 24 }, "conditions": { "requested": [ { "name": "type 2 diabetes mellitus", "proportion": 0.3, "assigned": 6, "code": "44054006", "display": "Type 2 diabetes mellitus", "patients": 8 } ], "most_common": [ { "code": "38341003", "display": "Hypertensive disorder", "patients": 13 } ] } } ``` For each requested condition, `assigned` is the number of patients it was given to, and `patients` the number who have it, including those in whom it arose naturally. Counts follow the SNOMED CT hierarchy: a patient with a more specific kind of a condition, or a condition due to it (renal disorder due to type 2 diabetes, for type 2 diabetes), counts for it. `most_common` lists up to 15 conditions, counted the same way. ## When some patients fail If a patient cannot be generated, the others are still delivered. The cohort succeeds, the patient is listed in `summary.failures` with its error, and it is not billed. If every patient fails, the cohort fails. ## Cancelling `DELETE /v1/cohorts/{cohort_id}` cancels the cohort: queued patients at once, and running ones when they finish. A canceled cohort has no results and is not billed.