Track an Ingestion

Ingestion is asynchronous. An ingest call answers 202 with a receipt once the payload is validated, before any of its data can be queried. Poll that receipt to know when the work is done.

PrerequisitesCopy Anchor Link

• The ingestionId returned by Ingest a FHIR Bundle, Ingest a CDA Document or Ingest Sessions.
• An access token with the read scope, as described in Authentication and Credentials.

Poll the receiptCopy Anchor Link

curl "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/ingestions/{ingestionId}" \
  -H "Authorization: Bearer <access-token>"

Poll until status is succeeded, partial or failed. The possible values are:

• pending - Accepted, work not started
• processing - In progress
• succeeded - Everything landed and can be queried
• partial - Every item was read, but some processing steps did not complete. Re-sending does not restart them
• failed - The work stopped before finishing (see failure)

Every field of the receipt is documented in Get an ingestion.

Wait for a whole patientCopy Anchor Link

To check every submission for a patient at once, list the ones still in progress:

curl "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/ingestions?status=pending,processing" \
  -H "Authorization: Bearer <access-token>"

meta.total is the number of submissions still in progress. Zero means everything sent for this patient has settled.

Check what was not usedCopy Anchor Link

intake lists what the submission held, grouped by kind. Each entry's outcome says what was done with that kind. The possible values are:

• structured - Clinical detail was read from it
• text_only - Kept as text, with no clinical detail read from it
• ignored - Not used at all (see reason)

An ignored entry's reason says whether there is something to fix. The possible values are:

• unsupported - The engine does not read this kind of item, so there is nothing to fix
• unusable - The item is missing something the engine needs, such as a code or text

List what was extractedCopy Anchor Link

staged counts the facts, events, narratives and messages the submission added. To list the extracted facts themselves, filter on the submission's ingestionId:

curl -X POST "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/graph/nodes/extracted_fact/query" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "ingestionId": { "eq": "{ingestionId}" } } }'

The same filter works on extracted_narrative and extracted_clinical_event nodes, as described in the graph query reference. These records are what was read from the submission, before the engine merged them into the patient's facts. A record keeps the ingestionId of the submission that first sent it, so a re-send of the same content does not match its own ingestionId.

Handle a partial or failed submissionCopy Anchor Link

Log failure.code and failure.message. The codes returned are not a fixed list, so avoid logic that depends on specific values.

The engine does not retry a submission once it is partial or failed. Re-sending the same content does not restart it either, because content the engine already holds is not staged again.

When every staged count is zero, intake says why. Entries that read ignored mean nothing in the payload could be used. Any other outcome means the content was already stored.

GotchasCopy Anchor Link

• There are no webhooks. Polling is the only way to follow a submission.
• A patient's submissions are processed one batch at a time. A submission that arrives while a batch is running waits for it.

Next stepsCopy Anchor Link

• The Patient Graph explains how extracted records are merged into the patient's record.
• How Agents Get Patient Context explains how agents read the record once it has settled.