Overview
An intelligence run is the record the Interchange Merchandising Engine writes each time it answers a buyer’sget_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 customer 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 |
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 |
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.
Related
Seller analytics
The aggregate view across many runs.
Buyer instructions
The rows the resolver matches per run.