List intelligence runs

GET /api/v2/storefront/intelligence-runs Returns a paginated list of intelligence-run records for your storefront, newest first. Each row captures the prompt, raw + parsed model output, matched buyer instructions, and the result envelope. Use skip and take to page.

Request

curl

curl "https://api.interchange.io/api/v2/storefront/intelligence-runs?skip=0&take=20" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Filter to one brief outcome — for example, the demand your storefront declined (your demand inbox) — and/or search the brief text:

curl

curl "https://api.interchange.io/api/v2/storefront/intelligence-runs?disposition=declined_fit&q=fintech" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Param	In	Type	Required	Notes
`skip`	query	integer	No	Number of rows to skip for pagination (default `0`)
`take`	query	integer	No	Number of rows to return per page, `1`–`100` (default `25`)
`disposition`	query	string	No	Demand-inbox filter — return only runs with this brief outcome: `responded`, `declined_fit`, `declined_policy`, or `not_live`. Omit to return every outcome. An invalid value returns `400`. See dispositions.
`q`	query	string	No	Case-insensitive substring search over the buyer brief text (1–200 chars), e.g. `fintech`. Combines with `disposition`. A value over 200 characters returns `400`.

Response

Returns an array of intelligence-run records (newest first). Pagination totals are in the meta.pagination object (offset-based: skip, take, total, hasMore) — see Pagination.

[
  {
    "id": "42",
    "storefrontId": "1234",
    "buyerCustomerId": 5678,
    "operatingInstructionsVersion": 3,
    "buyerScope": { "operatorDomain": "acme-media.com", "brandDomain": "northwind.example", "country": "US" },
    "buyerInstructions": { "matchedRowIds": ["17"], "effectiveDiscountPercent": 15, "notes": ["Brand requires acme-agency viewability ≥ 70%."] },
    "brief": "Premium CTV for a Q3 product launch",
    "buyingMode": "decisioned",
    "inventorySnapshot": {},
    "prompt": "Compose products for the buyer brief...",
    "rawLlmOutput": {},
    "parsedOutput": {},
    "runRationale": "Two CTV products matched the brief and budget.",
    "explanation": {
      "summary": "Selected 2 CTV products.",
      "selectedProducts": [],
      "unpricedProducts": [],
      "buyerInstructionNotes": ["Brand requires acme-agency viewability ≥ 70%."],
      "pricingNotes": [],
      "failure": null
    },
    "composedProductIds": ["prod_ctv_premium", "prod_ctv_sports"],
    "result": { "kind": "ok", "code": null, "message": null },
    "modelProvider": "anthropic",
    "modelName": "claude-sonnet",
    "durationMs": 1840,
    "refineSnapshot": null,
    "refinementAppliedSnapshot": null,
    "requestAsks": [],
    "shownProductsSnapshot": {},
    "pricingSummary": {},
    "negotiationSummary": {
      "qualification": {
        "qualified": true,
        "would_decline": false,
        "disposition": "responded",
        "enforced": false,
        "reason_axis": null,
        "reason": "qualified",
        "facets": { "detectedVertical": "sports", "detectedChannel": "ctv", "detectedGeo": "US" },
        "layer1_hit": false,
        "routed": true,
        "model": "claude-haiku-4-5-20251001",
        "latency_ms": 240,
        "input_tokens": 320,
        "output_tokens": 12
      }
    },
    "commercialOutcome": {},
    "evalLabel": null,
    "createdAt": "2026-06-06T15:00:00.000Z"
  }
]

See Intelligence runs overview for the full field reference on each record — including every negotiationSummary.qualification field.

Dispositions

Before composing a response, your storefront runs a brief-qualification gate that decides whether a brief is worth responding to. Every brief is recorded with a disposition under negotiationSummary.qualification.disposition, and ?disposition= filters the list to one outcome — your demand inbox:

Disposition	Meaning
`responded`	The storefront composed a response for the brief.
`declined_fit`	Declined — the brief matched no inventory the storefront sells. The response returned no products.
`declined_policy`	Declined — the brief violated the storefront’s acceptance policy. The response returned no products.
`not_live`	Brief arrived before the storefront was live. Reserved — not yet emitted.

A declined run returns no products and is recorded as a skipped result; the seller’s decline reason is never exposed to the buyer:

{
  "id": "57",
  "brief": "B2B fintech lead-gen on LinkedIn",
  "buyingMode": "brief",
  "composedProductIds": [],
  "result": { "kind": "skipped", "code": "brief_declined", "message": "Brief declined by the qualification gate." },
  "negotiationSummary": {
    "qualification": {
      "qualified": false,
      "would_decline": true,
      "disposition": "declined_fit",
      "enforced": true,
      "reason_axis": "fit",
      "reason": "wrong vertical",
      "facets": { "detectedVertical": "finance", "detectedChannel": null, "detectedGeo": null },
      "layer1_hit": false,
      "routed": true,
      "model": "claude-haiku-4-5-20251001",
      "latency_ms": 210,
      "input_tokens": 280,
      "output_tokens": 6
    }
  }
}

Errors

400 VALIDATION_ERROR — malformed skip or take, a disposition value outside the allowed set, or a q longer than 200 characters.
401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Intelligence run tasks

All intelligence-run operations.

Get intelligence run

Fetch one run in full.

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

Request

Parameters

Response

Dispositions

Errors

Intelligence run tasks

Get intelligence run

​Request

​Parameters

​Response

​Dispositions

​Errors

​Related

Intelligence run tasks

Get intelligence run

Request

Parameters

Response

Dispositions

Errors

Related