> ## 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.

# List intelligence runs

> Paginate the intelligence-run records on your storefront, newest first

`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

```bash curl theme={null}
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:

```bash curl theme={null}
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](#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](/v2/reference/pagination).

```json theme={null}
[
  {
    "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](/v2/storefront/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:

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Intelligence run tasks" href="/v2/storefront/intelligence-runs/tasks" icon="list-check">
    All intelligence-run operations.
  </Card>

  <Card title="Get intelligence run" href="/v2/storefront/intelligence-runs/tasks/get-intelligence-run" icon="magnifying-glass">
    Fetch one run in full.
  </Card>
</CardGroup>