Stream discovery events

GET /api/v2/buyer/discovery/{discoveryId}/events Opens a Server-Sent Events stream that pushes each newly landed seller group from a progressive discovery as it lands, instead of you polling Browse products with sinceRevision. Same continuation contract, delivered as a stream: the server watches the discovery snapshot server-side and emits an event whenever the revision advances. This is a REST/browser-friendly alternative for callers that want push instead of poll — MCP clients get the equivalent behavior for free via progress notifications during the tool call, then continue with browse_discovery?sinceRevision.

Request

The discovery session must already exist — start one with Discover products using progressive: true first.

curl

curl -N "https://api.interchange.io/api/v2/buyer/discovery/disc_01HZX3YQ7K9R6V3M2P1E0F8B2T/events" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Accept: text/event-stream"

EventSource

const events = new EventSource(
  `https://api.interchange.io/api/v2/buyer/discovery/${discoveryId}/events`,
  { withCredentials: true }, // send your session cookie or use a fetch-based SSE client for Bearer auth
)

events.addEventListener('revision', (e) => {
  const { revision, resultsComplete, pendingAgents, productGroups } = JSON.parse(e.data)
  render(productGroups) // replace-by-groupId, same as a sinceRevision poll
})

events.addEventListener('complete', (e) => {
  const { incompleteAgents } = JSON.parse(e.data)
  events.close()
})

Parameters

Field	Type	Required	Notes
`discoveryId`	string	Yes	Path param — session to stream

Response

Content-Type: text/event-stream. The stream emits these named events, each a data: line of JSON:

Event	When	Payload
`ready`	Immediately on connect	`{ discoveryId }`
`revision`	Whenever the snapshot’s revision advances	`{ discoveryId, revision, resultsComplete, productGroups, pendingAgents }` — `productGroups` contains only groups that landed since the previous revision you saw, using the same replace-by-`groupId` semantics as a `sinceRevision` poll
`complete`	Once, when `resultsComplete` becomes `true`	`{ discoveryId, revision, incompleteAgents }` — the stream ends immediately after
`error`	On an internal failure or the stream’s max duration	`{ code, message }` — the stream ends immediately after
`: ka`	Every ~15 seconds while otherwise idle	Comment line (no `event:`/`data:`), ignored by SSE parsers — keeps proxies from closing an idle connection

Worked example — a discovery with two sellers still outstanding, then completion:

event: ready
data: {"discoveryId":"disc_01HZX3YQ7K9R6V3M2P1E0F8B2T"}

event: revision
data: {"discoveryId":"disc_01HZX3YQ7K9R6V3M2P1E0F8B2T","revision":1,"resultsComplete":false,"pendingAgents":[{"agentId":"agent_slow_media","agentName":"Slow Media Storefront"},{"agentId":"agent_ctv_net","agentName":"CTV Network"}]}

: ka

event: revision
data: {"discoveryId":"disc_01HZX3YQ7K9R6V3M2P1E0F8B2T","revision":2,"resultsComplete":false,"productGroups":[{"groupId":"ctx_disc-group-2","groupName":"CTV Network","products":["..."]}],"pendingAgents":[{"agentId":"agent_slow_media","agentName":"Slow Media Storefront"}]}

event: revision
data: {"discoveryId":"disc_01HZX3YQ7K9R6V3M2P1E0F8B2T","revision":3,"resultsComplete":true,"productGroups":[{"groupId":"ctx_disc-group-0","groupName":"Slow Media Storefront","products":["..."]}]}

event: complete
data: {"discoveryId":"disc_01HZX3YQ7K9R6V3M2P1E0F8B2T","revision":3}

The connection closes automatically after the complete event, on a hard 5-minute cap, or when you close it client-side. pendingAgents (still answering) is distinct from incompleteAgents (timed out or answered partially at the final revision) — same distinction as the poll contract.

The stream is served from whichever pod handles your connection, which is not necessarily the pod running the discovery fan-out. It polls the shared discovery snapshot server-side on your behalf (about once a second) — you don’t need to poll anything yourself once the stream is open.

Errors

Errors before the stream opens use the standard JSON error envelope, since no event: frame has been written yet:

401 UNAUTHORIZED — missing or invalid auth.
404 NOT_FOUND — discoveryId does not exist or is not visible to the authenticated account.
400 VALIDATION_ERROR — the discovery session exists but is not active.

See Errors for the full error contract. Once the stream has opened, failures surface as an error event instead — the connection cannot switch back to a JSON response body.

Discover products

Run discovery and open a progressive session

Browse products

Poll for the same revisions instead of streaming

Discovery overview

Sessions, refinement, proposals, and storefronts

Webhooks

Get the same revisions pushed to your own endpoint instead

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Request

Parameters

Response

Errors

Discover products

Browse products

Discovery overview

Webhooks

​Request

​Parameters

​Response

​Errors

​Related

Discover products

Browse products

Discovery overview

Webhooks

Request

Parameters

Response

Errors

Related