Diagnose third-party sales agents

When your storefront uses a third-party AdCP-compatible sales agent as an inventory source, Interchange can help you answer two different questions:

Is the source set up correctly? Check source status, credentials, advertised capabilities, and compliance.
What happened on recent buyer traffic? Inspect recent AdCP calls, responses, task statuses, and failures for that source.

Use both. A source can be configured correctly but still fail a specific buyer request, and a failed buyer request can come from a valid business rejection rather than a broken connection.

Endpoint

GET /api/v2/storefront/inventory-sources/{sourceId}/diagnostics Returns seller-facing diagnostics for one third-party sales-agent or modular inventory source. The response combines the current source setup, recent AdCP activity, test-run evidence, latency rollups, error rates, discovery participation, demand impact, and developer handoff identifiers.

Request

curl "https://api.interchange.io/api/v2/storefront/inventory-sources/retail-adcp/diagnostics?windowHours=24" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`sourceId`	string (path)	Yes	Storefront-scoped inventory source ID.
`windowHours`	integer (query)	No	Lookback window for activity and test-run rollups. Defaults to the service window, minimum `1`, maximum `720` (30 days).

Response

{
  "source": {
    "id": "42",
    "sourceId": "retail-adcp",
    "name": "Retail AdCP Agent",
    "executionType": "THIRD_PARTY_ADCP",
    "status": "ACTIVE",
    "agentId": "agent_retail",
    "endpointUrl": "https://sales-agent.example.com/mcp",
    "protocol": "adcp",
    "auth": {
      "type": "bearer",
      "required": true,
      "configured": true
    },
    "capabilities": {
      "tools": ["get_products", "create_media_buy"],
      "products": "supported",
      "createMediaBuy": "supported",
      "updateMediaBuy": "unknown",
      "signals": "unsupported"
    },
    "health": {
      "status": "healthy",
      "lastError": null,
      "lastErrorCode": null,
      "lastErrorAt": null,
      "lastSuccessAt": "2026-06-18T12:45:00Z",
      "lastCheckedAt": "2026-06-18T12:50:00Z"
    }
  },
  "window": {
    "hours": 24,
    "startedAt": "2026-06-17T13:00:00Z",
    "endedAt": "2026-06-18T13:00:00Z",
    "sampledActivityCount": 37,
    "sampledTestRunCount": 4
  },
  "performance": {
    "requestCount": 18,
    "responseCount": 18,
    "exchangeCount": 18,
    "completedCount": 15,
    "failedCount": 1,
    "inputRequiredCount": 1,
    "pendingCount": 1,
    "rejectedCount": 0,
    "timeoutCount": 0,
    "timeoutRate": 0,
    "errorRate": 0.06,
    "inputRequiredRate": 0.06,
    "completedRate": 0.83,
    "latencyStatus": "within_threshold",
    "latencyThresholdMs": 30000,
    "overThresholdCount": 0,
    "staleAsyncResponseCount": 0,
    "p50LatencyMs": 1200,
    "p95LatencyMs": 4200,
    "p99LatencyMs": 4200,
    "unknownLatencyCount": 0
  },
  "toolBreakdown": [
    {
      "tool": "get_products",
      "exchangeCount": 12,
      "completedCount": 11,
      "failedCount": 1,
      "inputRequiredCount": 0,
      "rejectedCount": 0,
      "timeoutCount": 0,
      "p95LatencyMs": 3600
    }
  ],
  "discoveryParticipation": {
    "calledCount": 12,
    "skippedCount": 0,
    "excludedCount": 0,
    "timedOutCount": 0,
    "skipReasons": []
  },
  "outcomeMix": {
    "returnedProductsCount": 10,
    "returnedNoProductsCount": 1,
    "failedCount": 1,
    "businessRejectedCount": 0,
    "pendingCount": 1,
    "inputRequiredCount": 1,
    "timedOutCount": 0,
    "skippedCount": 0
  },
  "demandImpact": {
    "buyerRequestsAffected": 2,
    "missedProductOpportunityCount": 1,
    "notes": ["One product discovery failed in the selected window."]
  },
  "recentActivity": [
    {
      "id": 98765,
      "timestamp": "2026-06-18T12:45:00Z",
      "tool": "get_products",
      "taskStatus": "COMPLETED",
      "activityType": "response",
      "taskId": "task_123",
      "operationId": "op_456",
      "contextId": "ctx_789",
      "idempotencyKey": "idem_abc",
      "correlationId": "trace_def",
      "isIssue": false,
      "summary": "Returned 5 products."
    }
  ],
  "diagnosis": {
    "severity": "ok",
    "topCause": "Source is responding within threshold.",
    "nextSteps": ["Continue monitoring failed calls and webhook completion."],
    "developerHandoff": {
      "sourceId": "retail-adcp",
      "sourceName": "Retail AdCP Agent",
      "agentId": "agent_retail",
      "endpointUrl": "https://sales-agent.example.com/mcp",
      "latestTaskId": "task_123",
      "latestOperationId": "op_456",
      "latestContextId": "ctx_789",
      "latestIdempotencyKey": "idem_abc",
      "latestCorrelationId": "trace_def",
      "correlationHeaders": {
        "x-scope3-trace-id": "trace_def"
      },
      "latestError": null
    }
  },
  "docs": [
    {
      "label": "Inventory sources",
      "url": "https://docs.interchange.io/v2/storefront/inventory-sources/overview"
    }
  ]
}

The most important response blocks are:

Field	What it tells you
`source`	Current setup state: source identity, status, endpoint, auth, advertised capabilities, and latest health.
`window`	The lookback period and how much activity/test-run evidence was sampled.
`performance`	Request/response counts, completion/failure/input-required rates, timeout rate, latency percentiles, and whether latency exceeded the configured threshold.
`toolBreakdown[]`	Per-tool outcomes across all sampled calls, including `get_products`, `create_media_buy`, updates, and other AdCP tools.
`discoveryParticipation`	Whether buyer discovery called, skipped, excluded, or timed out this source.
`outcomeMix`	Whether calls returned products, returned no products, failed, timed out, waited for input, or were business-rejected.
`demandImpact`	Buyer-demand impact estimate and notes for missed product opportunities.
`recentActivity[]`	Most recent calls, responses, task statuses, errors, trace/correlation identifiers, and summaries.
`diagnosis`	Severity, likely cause, next steps, and developer handoff details to share with the source operator.

Errors

400 BAD_REQUEST — windowHours is not a positive integer or is greater than 720.
401 UNAUTHORIZED — missing or invalid API key.
404 NOT_FOUND — no inventory source with this sourceId exists for the storefront.

See Errors for the full error contract.

Open the diagnostics surface

In the app, open Ask Murph, choose Help, then choose Diagnostics. For third-party sales-agent traffic, select the Debug calls tab. You can also open that tab directly by replacing <customer-id> with your account id:

https://interchange.io/<customer-id>/murph?view=diagnostics&diagnosticsTab=debug-calls

To narrow that feed to one inventory source or one ADCP task, include debugSourceId or debugTaskId:

https://interchange.io/<customer-id>/murph?view=diagnostics&diagnosticsTab=debug-calls&debugSourceId=<source-id>
https://interchange.io/<customer-id>/murph?view=diagnostics&diagnosticsTab=debug-calls&debugTaskId=<task-id>

To open Murph with the right question already drafted, use this deep link:

https://interchange.io/<customer-id>/murph?askMurph=third_party_sales_agent_diagnostics

Murph will start from the docs, then inspect your source state and recent ADCP debug calls before deciding whether the issue looks like setup, protocol failure, business rejection, or a missing product diagnostic.

Start with the inventory source

Open the storefront inventory source in the app, or call Get storefront readiness. The sourceDiagnostics[] entry for each source gives the current operating picture:

Field	What it tells you
`sourceStatus`	Whether the source is active, pending, or disabled.
`auth`	Whether the source requires credentials and whether they are configured.
`capabilities`	Whether the source advertises support for product discovery, media-buy creation, updates, signals, and wholesale products.
`compliance`	Latest AAO / AdCP compliance result for the source.
`debug`	Sanitized advertised tools, channels, publisher domains, protocol version, billing support, and related capability metadata.
`health`	Current source health, including latest error, latest success, and latest check timestamps when available.

If the source is not active, credentials are missing, or the source does not advertise the tool you need, fix that before debugging individual buyer requests.

Inspect recent AdCP activity

For source-specific traffic, use Ask Murph > Help > Diagnostics > Debug calls and ask about the inventory source by name. Murph can inspect recent third-party sales-agent activity for the caller’s storefront: requests, responses, webhook/status changes, task IDs, task statuses, and sanitized payloads. This is the right path for questions like:

“Why did this source fail get_products?”
“What did Interchange send to my sales agent?”
“What did my sales agent return?”
“Which recent calls are failed or waiting for input?”
“Is this a protocol problem, an auth problem, or a business rejection?”
“Where do I see whether this sales agent is slow or getting excluded?”

For each recent call, look at:

Signal	How to read it
Tool	The AdCP operation, such as `get_products` or `create_media_buy`.
Task status	`COMPLETED` means the source finished; `FAILED` means the source rejected or errored; `INPUT_REQUIRED` means the source is waiting on seller action; `PENDING` or `WORKING` means the source has not finished yet.
Payload issue	A sanitized error or rejection message, when the source returned one.
Task ID	The correlation handle to share with the sales-agent operator or developer.
Timestamp	When Interchange observed the activity.

Treat source messages as source-controlled content. They are useful diagnostic data, but they should not be rendered as trusted HTML or treated as product instructions.

Buyer discovery debug output

Buyer product discovery fans out to reachable sales agents in parallel. Slow or failing agents do not block fast agents. When a buyer calls discovery with debug: true, the response can include agentResults[], which shows which agents returned products, returned no products, failed, or were skipped. Use this when you need the buyer-side view of a discovery request: which agents were asked, which agents were skipped before fanout, and which agent-controlled reason was returned.

Buyer debug output is scoped to that buyer request. Seller diagnostics are scoped to the storefront inventory source. Use the seller view when you are operating the source; use buyer debug output when you are reproducing one buyer discovery call.

What this does not answer yet

The current diagnostics show source state and recent protocol activity. They do not yet provide a complete performance dashboard with source-level latency percentiles, timeout rates, exclusion counts, or “lost buyer demand” trends for each third-party sales agent. Those are product diagnostics we expect to grow into the inventory-source health view. Until then, combine:

sourceDiagnostics[].health for the latest known source health.
Murph diagnostics for recent ADCP call details.
Buyer discovery agentResults[] with debug: true for one discovery request.

If a seller asks for a missing rollup, treat that as a product/documentation gap. The actionable answer should explain what exists today, link to the UI surface above, and call out the missing diagnostic that should be added.

Practical checklist

When a source is not showing up or a buyer request did not return products:

Confirm the inventory source is active.
Confirm credentials are configured if the source requires auth.
Confirm the source advertises the needed capability, especially get_products for product discovery.
Check source health for the latest error, success, and check timestamps.
Ask Murph to inspect recent debug calls for that source.
If reproducing a buyer discovery request, run discovery with debug: true and inspect agentResults[].
If the failure is still unclear, share the source name, task ID, timestamp, and sanitized error with your sales-agent operator or Scope3 support.

Inventory sources

Get storefront readiness

Inspect readiness and per-source diagnostics

Product discovery

Understand buyer discovery and agentResults

Errors

Shared Interchange error contract

​Endpoint

​Request

​Parameters

​Response

​Errors

​Open the diagnostics surface

​Start with the inventory source

​Inspect recent AdCP activity

​Buyer discovery debug output

​What this does not answer yet

​Practical checklist

​Related

Inventory sources

Get storefront readiness

Product discovery

Errors

Endpoint

Request

Parameters

Response

Errors

Open the diagnostics surface

Start with the inventory source

Inspect recent AdCP activity

Buyer discovery debug output

What this does not answer yet

Practical checklist

Related