The event stream

The stream is the engine’s own progress spine, passed through the gateway verbatim — we do not maintain a second, prettier vocabulary that could drift from reality. This page blesses the stable subset integrators may rely on, and its examples are regenerated from captured live streams (2026-08-27) — where an earlier draft of this page disagreed with the wire, the wire won. Two rules make it safe to build on:

Unknown phases are liveness. Any event whose phase you don’t recognize means “the run is alive.” Render nothing, never error. New phases are additive and ship without a version bump.
Guaranteed fields only. Each event below lists the fields guaranteed present. Other fields may appear and may change without notice.

One honest wart, stated plainly: event payloads use the engine’s camelCase (costUsd, elapsedMs) while REST request/response bodies use snake_case (max_spend_usd, spend_usd). The stream is the engine’s wire format, verbatim — renaming it would mean a translation layer that could lie.

Transport

GET /v1/sessions/{id}/stream is text/event-stream. Each SSE message: id: = the event’s sequence number, data: = one JSON event. Resume with Last-Event-ID; the same numbers page GET …/events?after=. Sequence numbers are global per session, monotonic across turns. Full transport semantics: Ways to watch a run. The first message of a live run is the meta envelope:

id: 0
data: {"kind":"meta","reqId":"sess_9m2kd","sessionId":"sess_9m2kd"}

The paged replay envelope (`GET …/events`)

The paged log serves the same event objects, flat, with seq merged in — the event is not nested under a data or event member:

{
  "data": [
    { "seq": 2, "phase": "search-intent", "query": "…", "entity": "record", "confidence": 0.92 },
    { "seq": 3, "phase": "search-resolve", "merchants": [{ "domain": "waxwing.example" }] }
  ],
  "has_more": false,
  "next": 3
}

seq is the SSE id: for that event. Rebuild-then-attach (page …/events from 0 to rebuild state, then connect …/stream with Last-Event-ID = the last seq) is the reload/resume recipe.

The stable subset

`search-intent` — what the parse understood ($0)

Captured live (trimmed):

{
  "phase": "search-intent",
  "query": "vinyl records under $30 in austin",
  "entity": "record",
  "merchant": "record store",
  "predicate": [{ "field": "price", "op": "<", "value": 30, "unit": "USD" }],
  "geo": { "region": "Austin, TX", "countryCode": "US" },
  "constraints": 1,
  "confidence": 0.92
}

Guaranteed: phase, query, entity, confidence (a number, 0–1). The wire shape, as measured:

constraints is a count (a number). The parsed constraint objects ride predicate — an array of { field, op, value, unit? } objects. Constraint field names are per-query vocabulary (the same query may parse to ingredient/strength one run and vitamin/dosage the next) — treat them as data, not an enum.
geo is an object (region, countryCode, …) when present, and may be absent.
merchant (a prose merchant descriptor) may appear when the query pins one.

confidence is a number, 0–1, on every event — no surface emits the enum words ("high"/"low") that earlier drafts showed. One known wire inconsistency, stated: POST /v1/sessions/estimate currently returns parsed.confidence as a string-wrapped float ("0.92"). The number form is canonical; the estimate’s string form is a documented divergence that will be fixed as a dated-version change.

`search-resolve` — the merchant fan-out plan ($0)

Captured live (trimmed):

{
  "phase": "search-resolve",
  "merchants": [
    { "domain": "waxwing.example", "seedUrl": "https://waxwing.example/" },
    { "domain": "spindlecity.example", "seedUrl": "https://spindlecity.example/" }
  ],
  "ms": 1490
}

Guaranteed: phase, merchants — an array of merchant objects, each guaranteed domain (seedUrl and an evidence provenance string may ride along). The fan-out count is merchants.length. (An earlier draft documented merchants as a number; the wire has always carried the array — the array is the contract.)

`orchestrate` — a routing decision (why money moved)

Captured live (trimmed):

{
  "phase": "orchestrate",
  "action": "dispatched",
  "url": "https://well.ca/brand/cerave.html",
  "domain": "well.ca",
  "reason": "Intent targets CeraVe at well.ca; this is the CeraVe brand catalog page (68 products)…"
}

action ∈ dispatched | declined | re-resolved | proposed | stopped (open enum). Guaranteed: phase, action, reason. (The field is action — an earlier draft called it decision; the wire has always said action.) A declined carries by ("pool" | "duplicate-guard"). These events are the audit trail of spend: every dispatch and every decline, with the reason, in the same stream as the rows. During the quiet stretches of a run they may be the only substantive traffic — that’s normal.

`search-source` — a source delivered (rows ride the event)

{
  "phase": "search-source",
  "domain": "endofanear.shop",
  "url": "https://endofanear.shop/collections/all",
  "delivered": true,
  "records": 142,
  "costUsd": 0.41,
  "elapsedMs": 49000,
  "complete": true,
  "rows": [{ "title": "…", "price": 8.79, "currency": "CAD", "url": "https://…" }],
  "truncated": { "cap": "rows", "limit": 500 }
}

Guaranteed: phase, domain, delivered, records. costUsd may be null — cost basis unavailable, which settles at $0. Like every dollar amount on this API, costUsd is the customer’s price, rounded to ≤4 decimals.

delivered decides whether this pass gets a receipt — costUsd does not. A pass with delivered: true produces one receipt on GET …/receipts. A pass with delivered: false produces none, even when its costUsd is non-null and was billed — the common case for a pass stopped by a deadline, an anti-bot wall or a dead transport. Don’t infer a receipt from the presence of a cost: what a receipt covers.

rows is a bounded preview (500 rows / 1.5 MB per source, stated in truncated); the full corpus is at GET …/rows. Stream rows are flat per-source records — see the three row dialects.

`cost` — the orchestrator’s own model spend

{ "phase": "cost", "usd": 0.006 }

Guaranteed: phase, usd (may be null).

`search-done` — the run’s terminal (not the turn’s)

{
  "phase": "search-done",
  "sources": 3,
  "delivered": 2,
  "records": 228,
  "elapsedMs": 262000,
  "stop": "agent-settled",
  "unchecked": [{ "domain": "waxcellar.shop", "stage": "triage" }]
}

stop ∈ exhausted | query-budget | spend-budget | agent-settled | stopped (open enum). Guaranteed: phase, stop, records. Two honest details here:

unchecked lists merchants that were never dispatched — a fact about us, stated, not hidden. Coverage you didn’t get is named.
A record ending at search-done is a turn still judging, not a lost answer. Wait for search-answer and the terminal envelope.

`search-adjudication` — the judging window is never silent

{ "phase": "search-adjudication", "started": true, "residual": 183 }

A completion event with tallies always follows. Guaranteed: phase.

`search-answer` — the authoritative summary (bounded by construction)

{
  "phase": "search-answer",
  "qualified": 41,
  "needsVerification": 6,
  "rejected": 181,
  "rows": [{ "title": "…", "price_listed": 8.79, "currency": "CAD", "product_id": "…" }],
  "truncated": { "cut": "dispositions" }
}

Guaranteed: phase, qualified. Sections shed adaptively by size, each cut named in truncated.cut. Rows the screen couldn’t verify are counted under needsVerification, not silently promoted to qualified. Answer rows are flat like source rows but with renamed fields (price_listed, product_id) — see the dialect table below.

`abstain` / `error` — honest endings

{ "phase": "abstain", "reason": "no purchasable entity in the query" }

{ "phase": "error", "message": "model stream error: Forbidden", "code": "model_unavailable" }

Guaranteed: phase, plus reason on an abstain and message on an error. A terminal error additionally carries code — the stable stream-terminal vocabulary; mid-run fail-soft error events may omit it. The session status and the ledger settle accordingly: an abstain is a **

0 outcome, stated** — only signed receipts settle, and the rest of the reservation is released. These are statuses, not HTTP errors (see [Errors](/errors), "Failures that are NOT errors"). A query we [decline to spend on](/errors/declined_to_spend) ends this way too — a `201` create, an `abstain` event, status `abstained`,

`session-turn` — a turn closed (SSE terminal envelope)

{
  "kind": "session-turn",
  "record": {
    "n": 1,
    "text": "vinyl records under $30 in Austin",
    "route": "run",
    "at": "2026-08-26T14:35:12Z"
  },
  "because": "first turn runs by definition"
}

route ∈ run | narrow | ask | reaim | unbound. A reaim record carries proposal: { estimatedUsd, passes, confirmed }. This envelope closes the stream for the turn.

The three row dialects — one session, three spellings

Rows appear on three surfaces, and today they are three different shapes. This is a documented wart, not a contract we defend — a future dated version should converge them — but until then, here is the mapping, as measured on live sessions:

Surface	Shape	Price field	Row id field	Source attribution
Stream `search-source.rows[]`	Flat per-source record (`{ title, price, currency, url, …per-source keys }`)	`price`	`id`	The enclosing event’s `domain`/`url` — rows carry no `source` wrapper
Stream `search-answer.rows[]`	Flat, same keys renamed on qualification	`price_listed`	`product_id`	None on the row — join back to source rows by id/title
REST `GET …/rows`	Enveloped: `{ source: { domain, url, receipt_id }, record: { …the flat record } }`	`record.price`	`record.id`	`source.domain` / `source.url` / `source.receipt_id` on every row
REST `GET …/result.rows[]`	Enveloped: `{ source: { domain, url }, record: { …the flat record } }`, plus `fulfillment`	`record.price`	`record.id`	`source.domain` / `source.url` — no `receipt_id`

Practical guidance: parse prices from price ?? price_listed (both are JSON numbers, with currency alongside); treat all other record keys as per-source schema. url may be an empty string on some rows; no image field is guaranteed to exist.

The two REST surfaces are not interchangeable, and the difference is the audit join. GET …/rows emits source.receipt_id on every row — it names the receipt of the pass that delivered that row, and it is what lets you reconcile a row against the receipts surface. GET …/result.rows[] does not carry it; it carries fulfillment (how the row satisfies the predicate, with evidence) and the adjudication’s duplicateCount / duplicateSources instead.Page …/rows for anything you intend to audit, and treat …/result.rows as a convenience view of the adjudicated subset.

Events not in the subset

harness heartbeats (per-pass phase pulses), search-locate, search-triage, orchestrate-turn/orchestrate-tool envelopes, acquisition/anti-bot cost events, and future phases all flow on the wire. Read them if useful; build on the subset. They can disappear or change shape without notice — the subset cannot.

Get started

Guides

Errors

Changelog

Transport

The paged replay envelope (`GET …/events`)

The stable subset

`search-intent` — what the parse understood ($0)

`search-resolve` — the merchant fan-out plan ($0)

`orchestrate` — a routing decision (why money moved)

`search-source` — a source delivered (rows ride the event)

`cost` — the orchestrator’s own model spend

`search-done` — the run’s terminal (not the turn’s)

`search-adjudication` — the judging window is never silent

`search-answer` — the authoritative summary (bounded by construction)

`abstain` / `error` — honest endings

`session-turn` — a turn closed (SSE terminal envelope)

The three row dialects — one session, three spellings

Events not in the subset

​Transport

​The paged replay envelope (GET …/events)

​The stable subset

​search-intent — what the parse understood ($0)

​search-resolve — the merchant fan-out plan ($0)

​orchestrate — a routing decision (why money moved)

​search-source — a source delivered (rows ride the event)

​cost — the orchestrator’s own model spend

​search-done — the run’s terminal (not the turn’s)

​search-adjudication — the judging window is never silent

​search-answer — the authoritative summary (bounded by construction)

​abstain / error — honest endings

​session-turn — a turn closed (SSE terminal envelope)

​The three row dialects — one session, three spellings

​Events not in the subset

Transport

The paged replay envelope (`GET …/events`)

The stable subset

`search-intent` — what the parse understood ($0)

`search-resolve` — the merchant fan-out plan ($0)

`orchestrate` — a routing decision (why money moved)

`search-source` — a source delivered (rows ride the event)

`cost` — the orchestrator’s own model spend

`search-done` — the run’s terminal (not the turn’s)

`search-adjudication` — the judging window is never silent

`search-answer` — the authoritative summary (bounded by construction)

`abstain` / `error` — honest endings

`session-turn` — a turn closed (SSE terminal envelope)

The three row dialects — one session, three spellings

Events not in the subset