Lifecycle and retries
Distinguish assessment state, session access, and individual attempts.
One Inquiry represents one intended assessment. A recoverable retry can happen inside that Inquiry; it does not require another customer record or another successful-result charge.
Read the task status
| Status | Meaning | Integration behavior |
|---|---|---|
created | Created but not actively running. A paused Vital Scan can return to this state. | Offer the existing valid Hosted Flow link. |
in_progress | The assessment has started; a result is not yet saved. | Show pending. Do not create another task on refresh. |
completed | A result has been saved. | Read and display it; do not run the same assessment again. |
failed | A Vital Scan attempt failed. It may still be retryable in its existing session. | Direct the user to the existing valid flow and its retry action. |
expired | The unfinished assessment's access window has elapsed. | Offer a new assessment explicitly. |
The access deadline is expiresAt, 24 hours after creation. Do not infer access
validity from status alone: a stored failure can remain failed after its deadline.
Saved completed results are not erased when launch access expires. An active
server-side analysis is allowed to finish under its processing lease.
Vital Scan: pause, fail, and retry
A pause stops the current attempt and releases its reserved credits. A recoverable scan failure records a reason and presents Scan again in the same flow. The user's basic information is retained. The new attempt receives its own execution identity so delayed messages from the old attempt cannot complete or release it.
The intended behavior is to retry without refreshing the page. A full progress bar is not completion: result processing and saving must also succeed. Do not mark your own business process complete until the Inquiry API reports completion.
AI Nutrition: processing and retry
The Hosted Flow prevents overlapping analysis for the same Inquiry. An unreadable
meal or a recoverable processing error can show a retry action while the task
remains in_progress; a failure does not always mean the public status becomes
failed. There are at most five accepted analysis attempts per Inquiry. A running
attempt or an exhausted attempt budget cannot be bypassed by opening more sessions.
Access links are separate from attempts
The resume endpoint issues a new session only for
eligible created or in_progress tasks before expiry. It cannot issue a new link
for failed or completed tasks. A recoverable failed Vital Scan uses its existing
valid session to retry.
Revoking one session does not delete the Inquiry or revoke every other session. Do not use the resume endpoint as a substitute for the Hosted Flow retry button.
Credits
For credit-managed enterprises, a service attempt reserves credits before costly work starts. Recoverable failure or pause releases that reservation. Successful result saving settles the assessment once. Reads and return-page refreshes do not settle it again. See Usage and credits.