Run Lifecycle

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

A run has a coarse status and a finer-grained phase. All endpoints here are owner-only (see authentication.md).

Statuses

`status`	Meaning
`pending`	Created, not yet started.
`running`	Actively executing.
`completed`	Finished successfully.
`failed`	Stopped with an error (`errorMessage` is set).
`cancelled`	Cancelled by the owner (`cancelReason` may be set).

Phases

While running, a run reports its current phase:

understand → plan → retrieve → reason → act → compose → deliver → done

phase is null before the run starts.

Reading a run

GET /v1/agent-runs/{runId}

Returns the run, its artifacts, and revisionDrift — whether the trip has advanced past the run's frozen input snapshot since it started.

{
  "run": { "id": "9f2a1c7e-…", "status": "running", "phase": "reason", "lastEventSequence": 14 },
  "artifacts": [ { "id": 5012, "artifactType": "candidates", "isPinned": false } ],
  "revisionDrift": { "hasDrift": false, "snapshotRevision": 7, "currentRevision": 7 }
}

If revisionDrift.hasDrift is true, the trip changed underneath the run; decide whether to apply its output or start a fresh run.

Control actions

POST /v1/agent-runs/{runId}/control

`action`	Effect
`start`	Begin a `pending` run.
`stop`	Halt a `running` run.
`retry`	Re-run after a `failed` outcome.
`cancel`	Cancel the run; pass an optional `reason`.

curl -s -X POST "https://api.travelmode.ai/v1/agent-runs/9f2a1c7e-…/control" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel", "reason": "User changed dates" }'

{ "run": { "id": "9f2a1c7e-…", "status": "cancelled", "cancelReason": "User changed dates" } }

An action that is invalid for the run's current state returns 400 (for example, start on a run that is already running).

status

Meaning

pending

Created, not yet started.

running

Actively executing.

completed

Finished successfully.

failed

Stopped with an error (errorMessage is set).

cancelled

Cancelled by the owner (cancelReason may be set).

Reading a run

GET /v1/agent-runs/{runId}

Returns the run, its artifacts, and revisionDrift — whether the trip has advanced past the run's frozen input snapshot since it started.

{ "run": { "id": "9f2a1c7e-…", "status": "running", "phase": "reason", "lastEventSequence": 14 }, "artifacts": [ { "id": 5012, "artifactType": "candidates", "isPinned": false } ], "revisionDrift": { "hasDrift": false, "snapshotRevision": 7, "currentRevision": 7 } }

If revisionDrift.hasDrift is true, the trip changed underneath the run; decide whether to apply its output or start a fresh run.

Control actions

POST /v1/agent-runs/{runId}/control

`action`	Effect
`start`	Begin a `pending` run.
`stop`	Halt a `running` run.
`retry`	Re-run after a `failed` outcome.
`cancel`	Cancel the run; pass an optional `reason`.

curl -s -X POST "https://api.travelmode.ai/v1/agent-runs/9f2a1c7e-…/control" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "action": "cancel", "reason": "User changed dates" }'

{ "run": { "id": "9f2a1c7e-…", "status": "cancelled", "cancelReason": "User changed dates" } }

An action that is invalid for the run's current state returns 400 (for example, start on a run that is already running).