Errand lifecycle

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; for the concept and composition model, see 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

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` — the agent task that produced the Errand.
`executing_agent_task`	Via `expand=executing_agent_task`. 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.

Errand guide — request/response shape and drive-the-lifecycle recipes.
Errands — concept page and composition with PINTs.
Enable Errands for a user — an end-to-end quickstart that walks the diagram above.
PINTs and scopes — the primitives an Errand rides on.

Introduction

Quickstarts

Guides

Product Guides

API Reference

State diagram

Status reference

How transitions map to the public API

Event stream

​State diagram

​Status reference

​How transitions map to the public API

​Event stream

​Related

State diagram

Status reference

How transitions map to the public API

Event stream

Related