> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Intelligence runs
> The per-request records the Merchandising Agent writes when it composes a response — prompt, output, products, and outcome.
## 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](/v2/storefront/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.
## Test a starter brief
The Storefront Briefs page includes starter briefs for evaluating discovery
before launch. Select **Run brief** to call your storefront with that brief and
see the result, matched products, and any retry state beside the starter. The
test is read-only, works while the storefront is still configuring, and stores
an intelligence run so you can select **Review decision** to inspect exactly
how the storefront reached its answer.
If you provide Murph with your own exact brief, Murph can run the same typed
test directly. Both paths use the shared MCP tool contract, so the workflow is
also available in other compatible hosts without copying a generated prompt
into chat.
## 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=`](/v2/storefront/intelligence-runs/tasks/list-intelligence-runs).
## Tasks
Paginate runs newest-first.
Fetch one run with full prompt and output.
Attach an evaluator label.
## Related
The aggregate view across many runs.
The rows the resolver matches per run.