# Track an Ingestion

URL: https://docs.clinia.com/docs/recorded-memory/track-an-ingestion

> Poll an ingestion receipt until the submission settles.



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.

## Prerequisites [#prerequisites]

* The `ingestionId` returned by [Ingest a FHIR Bundle](https://docs.clinia.com/docs/recorded-memory/ingest-fhir), [Ingest a CDA Document](https://docs.clinia.com/docs/recorded-memory/ingest-cda) or [Ingest Sessions](https://docs.clinia.com/docs/recorded-memory/ingest-sessions).
* An access token with the `read` scope, as described in [Authentication and Credentials](https://docs.clinia.com/docs/platform/authentication-and-credentials).

## Poll the receipt [#poll-the-receipt]

```bash
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](https://docs.clinia.com/api/rest/get-patients-patientId-ingestions-ingestionId).

## Wait for a whole patient [#wait-for-a-whole-patient]

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

```bash
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 used [#check-what-was-not-used]

`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 extracted [#list-what-was-extracted]

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

```bash
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](https://docs.clinia.com/api/rest/post-patients-patientId-graph-nodes-type-query). 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 submission [#handle-a-partial-or-failed-submission]

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.

<Callout type="warn" title="Re-sending stored content reports succeeded">
  Re-sending content the engine already holds returns a new receipt with every `staged` count at
  zero. That receipt settles as `succeeded` because the re-send created no work. It says nothing
  about the original content, so check the receipt of the submission that first sent it.
</Callout>

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.

## Gotchas [#gotchas]

* 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 steps [#next-steps]

* [The Patient Graph](https://docs.clinia.com/docs/recorded-memory/patient-graph) explains how extracted records are merged into the patient's record.
* [How Agents Get Patient Context](https://docs.clinia.com/docs/context-assembly/overview) explains how agents read the record once it has settled.
