Intelligence runs

Overview

An intelligence run is the record the Merchandising Agent writes each time it answers a buyer’s get_products request for your storefront. Each run captures the inputs (buyer scope, brief, matched buyer instructions), the prompt and raw + parsed model output, the products it composed, and a result envelope. Runs are the per-request detail behind your seller analytics — analytics aggregate runs; runs show you exactly what happened on one request. Use intelligence runs to audit how the engine responded, debug an unexpected composition, and label runs for evaluation workflows.

Run record fields

Field	Type	Description
`id`	string	Surrogate id
`storefrontId`	string	Storefront the run belongs to
`buyerCustomerId`	integer \| null	Buyer account id, when known
`operatingInstructionsVersion`	integer	Operating-instructions version active for the run
`buyerScope`	object	`{ operatorDomain, brandDomain, country }` extracted from the request
`buyerInstructions`	object	Resolver output: `{ matchedRowIds[], effectiveDiscountPercent, notes[] }`
`brief`	string \| null	Buyer brief that drove the run
`buyingMode`	string	Buying mode for the run
`inventorySnapshot`	any	Inventory considered for the run
`prompt`	string	The composed prompt sent to the model
`rawLlmOutput`	any	Raw model output
`parsedOutput`	any	Parsed model output
`runRationale`	string \| null	Engine rationale for the run
`explanation`	object	Buyer-safe explanation (see below)
`composedProductIds`	string[]	Product ids persisted for the response
`result`	object	Outcome envelope `{ kind (ok\|error\|skipped), code, message }`
`modelProvider`	string \| null	Model provider
`modelName`	string	Model used
`durationMs`	integer \| null	Run duration in milliseconds
`refineSnapshot`, `refinementAppliedSnapshot`	any	Refinement inputs and applied result
`requestAsks`	string[]	Buyer asks detected on the request
`shownProductsSnapshot`	any	Products shown to the buyer
`pricingSummary`	any	Pricing summary for the run
`negotiationSummary`	object	Compact seller-facing analytics. On brief-mode runs it also carries a `qualification` object — the brief-qualification gate’s verdict (see below)
`commercialOutcome`	any	Attributed commercial outcome
`evalLabel`	any	Evaluator label attached to the run, when present
`createdAt`	string	ISO 8601 timestamp

`explanation`

Field	Type	Description
`summary`	string	One-line summary of what the engine did
`selectedProducts[]`	array	Buyer-safe explanation per selected product: `{ productId, name, description, reasoning, pricing, bundleIds[], signalIds[], formatIds[] }` where each `formatIds[]` item is `{ agentUrl, id }`
`unpricedProducts[]`	array	Compositions omitted because they could not be priced authoritatively: `{ name, reasoning, reason, bundleIds[], signalIds[] }`
`buyerInstructionNotes[]`	string[]	Buyer-instruction notes applied
`pricingNotes[]`	string[]	Pricing notes
`failure`	object \| null	`{ code, message }` when the run failed

Each selectedProducts[].pricing is { baseCpm, currency, operatorDiscount, finalCpm }.

`negotiationSummary.qualification`

Present on brief-mode runs once the brief-qualification gate has run — the cheap classifier that decides whether the storefront should respond to a brief before composing. The gate weighs inventory fit and the storefront’s acceptance policy, fails open on any fault (composes), and records its verdict here on every brief.

Field	Type	Description
`qualified`	boolean	Gate verdict — `true` when the brief is worth composing for
`would_decline`	boolean	`!qualified`. The shadow signal: `true` even when the decline was not enforced (e.g. a fit decline while fit-enforcement is off), so you can see demand the gate would turn away
`disposition`	string \| null	Outcome bucket: `responded`, `declined_fit`, `declined_policy`, or `not_live`. The value `?disposition=` filters on
`enforced`	boolean	`true` only when the decline was acted on (`declined_fit` / `declined_policy`) — i.e. the run returned no products. `false` for `responded` and for shadow declines
`reason_axis`	string \| null	Why a decline: `fit` (no matching inventory) or `policy` (acceptance-policy violation); `null` when qualified
`reason`	string	Short reason for the verdict. Never exposed to the buyer
`facets`	object \| null	Signals the gate detected: `{ detectedVertical, detectedChannel, detectedGeo }`
`layer1_hit`	boolean	`true` when a pre-model check (e.g. empty brief) decided the verdict without a model call
`routed`	boolean	`true` when a model verdict was parsed; `false` means the gate failed open (fault/timeout/unparseable) and the run composed regardless
`model`	string	Model that produced the verdict
`latency_ms`	integer	Gate latency in milliseconds
`input_tokens`, `output_tokens`	integer	Token usage for the gate call

A storefront with an acceptance policy enforces declined_policy automatically; declined_fit is enforced only when fit-enforcement is enabled platform-wide. Until then a fit decline records would_decline: true with disposition: "responded" (shadow). Filter your demand inbox with ?disposition=.

Tasks

List intelligence runs

Paginate runs newest-first.

Get intelligence run

Fetch one run with full prompt and output.

Label intelligence run

Attach an evaluator label.

Seller analytics

The aggregate view across many runs.

Buyer instructions

The rows the resolver matches per run.

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Overview

Run record fields

`explanation`

`negotiationSummary.qualification`

Tasks

List intelligence runs

Get intelligence run

Label intelligence run

Seller analytics

Buyer instructions

​Overview

​Run record fields

​explanation

​negotiationSummary.qualification

​Tasks

List intelligence runs

Get intelligence run

Label intelligence run

​Related

Seller analytics

Buyer instructions

Overview

Run record fields

`explanation`

`negotiationSummary.qualification`

Tasks

Related