> ## Documentation Index > Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt > Use this file to discover all available pages before exploring further. # Errand lifecycle > State machine, transitions, and terminal states for an Errand (the IPA lifecycle on the wire). An Errand moves through a sequence of states as the agent qualifies the intent, searches, validates candidates, waits for approval, optionally monitors conditions, and executes. On the wire an Errand is the `IPA` (Intelligent Purchase Authorisation) lifecycle — the routes, states, and events below use the `IPA` identifiers unchanged. This page is the state-machine reference. For the API surface and request/response shape, see the [Errand guide](/guides/errand); for the concept and composition model, see [Errands](/concepts/errands). An Errand has three product phases that map onto the underlying states: | Phase | States | What happens | | ----------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Intent** | `qualifying`, `searching`, `validating`, `pending_clarification` | The agent qualifies the raw intent against the linked PINT, searches for candidates, scores them, and asks the user for clarification when needed. | | **Authorization** | `pending_approval`, `approved` | A valid candidate is surfaced for the user's decision; on approval the Errand is cleared to proceed. | | **Vigilance** | `monitoring`, `executing` | The agent watches live offers against any attached conditions, then executes the purchase when conditions are met. | Terminal states (`completed`, `failed`, `cancelled`, `expired`) close the Errand out of whichever phase it was in. ## State diagram ```mermaid theme={null} stateDiagram-v2 [*] --> qualifying : POST /v0/user/ipa qualifying --> searching : intent qualified qualifying --> pending_clarification : agent needs more info pending_clarification --> qualifying : PUT /answers searching --> validating : candidates produced validating --> pending_approval : validation passed pending_approval --> approved : PUT /decision (approved + signature) pending_approval --> cancelled : PUT /decision (rejected) pending_approval --> expired : approval timeout approved --> monitoring monitoring --> executing : conditions met or no conditions monitoring --> expired : monitor timeout executing --> completed : purchase executed executing --> failed : execution error qualifying --> failed : qualification error searching --> failed : search error validating --> failed : validation error qualifying --> cancelled : DELETE searching --> cancelled : DELETE validating --> cancelled : DELETE pending_approval --> cancelled : DELETE approved --> cancelled : DELETE monitoring --> cancelled : DELETE completed --> [*] failed --> [*] cancelled --> [*] expired --> [*] ``` ## Status reference | Status | Meaning | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `qualifying` | Pre-flight is parsing the raw intent and validating the linked PINT's scopes. | | `searching` | The agent is crawling for candidate products or services. | | `validating` | Candidates are being scored against the Errand's constraints. | | `pending_clarification` | The agent needs more information from the user. `clarification_questions` is populated and the `answers` link is available. | | `pending_approval` | A valid candidate is ready; the `decision` link is available. | | `approved` | The user has approved. The Errand then transitions into `monitoring`. | | `monitoring` | Entered after approval regardless of autonomy level. When `conditions` are attached they are evaluated against live offers; when `conditions` are empty the monitor signals readiness immediately and the Errand advances to `executing`. | | `executing` | The purchase transaction is in flight. | | `completed` | Terminal. Purchase was executed successfully. | | `failed` | Terminal. An error occurred during qualification, search, validation, or execution. `failure_reason` is populated. | | `cancelled` | Terminal. The user cancelled before completion. | | `expired` | Terminal. `monitor_until` elapsed without conditions being met. | ## How transitions map to the public API The following response fields are populated as the Errand advances: | Field | Populated when | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `preflight_workflow_id` | On create — a workflow identifier for the preflight that parses and qualifies the intent. | | `originating_agent_task` | Via [`expand=originating_agent_task`](/guides/errand#expansions) — the agent task that produced the Errand. | | `executing_agent_task` | Via [`expand=executing_agent_task`](/guides/errand#expansions). Spawned during pre-flight, so available before approval is granted. | | `pint_uris` | The PINTs *explicitly* linked to the originating and (once present) executing agent tasks. Near-always `null`: nothing links one for you, and the mandate an Errand spends under is reserved later in its lifecycle rather than recorded here. | | `failure_reason` | Populated when `status` reaches `failed`. | | `completed_at` | Populated when `status` reaches any terminal state. | The `_links` map on every response declares which actions the current state allows: | Link | Present when | | ---------- | ---------------------------------------- | | `self` | Always. | | `events` | Always. | | `answers` | `qualifying` or `pending_clarification`. | | `decision` | `pending_approval`. | | `cancel` | Any non-terminal status. | ## Event stream Every state change is recorded as an event. Fetch them with `GET /v0/user/ipa/{ipa_id}/events`, or embed them via `expand=events`. Event types include `ipa.status_change`, `ipa.clarification_sent`, `ipa.clarification_received`, `ipa.approval_requested`, `ipa.approval_received`, `ipa.workflow_started`, `ipa.workflow_completed`, `ipa.workflow_failed`, `ipa.cancelled`, `ipa.workflow_resumed`, `ipa.monitor_started`, and `ipa.price_checked`. ## Related * [Errand guide](/guides/errand) — request/response shape and drive-the-lifecycle recipes. * [Errands](/concepts/errands) — concept page and composition with PINTs. * [Enable Errands for a user](/guides/quickstarts/set-up-errand) — an end-to-end quickstart that walks the diagram above. * [PINTs](/identity/pint) and [scopes](/identity/scopes) — the primitives an Errand rides on.