Get products

GET /api/v2/buyer/discovery/{discoveryId}/products Returns the products currently selected in the session, with their per-product budget allocations and budget context. This is the selected-products cart you build with Add products and Apply proposal — distinct from the browsable discovery results. If totalProducts is 0, no product has been selected yet; it does not mean the discovery returned zero products or that results were lost.

Request

curl -X GET "https://api.apostra.com/api/v2/buyer/discovery/disc_01HZX3YQ7K9R6V3M2P1E0F8B2T/products" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

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

Response

{
  "discoveryId": "disc_01HZX3YQ7K9R6V3M2P1E0F8B2T",
  "products": [
    {
      "productId": "prod_acme_ctv_sports",
      "salesAgentId": "agent_acme_media",
      "bidPrice": 32.5,
      "budget": 150000,
      "groupId": "ctx_disc_01HZX3-group-0",
      "groupName": "Acme Media Connected TV",
      "selectedAt": "2026-06-07T15:04:00Z"
    }
  ],
  "totalProducts": 1,
  "selectionSummary": "This selected-products cart contains 1 product.",
  "budgetContext": { "sessionBudget": 250000, "allocatedBudget": 150000, "remainingBudget": 100000 }
}

budgetContext.remainingBudget is the session budget minus the sum of selected budget allocations. An empty products array means nothing has been added yet. To re-read what discovery returned, use Browse products, which keeps results available in its cache for four hours; after expiry, offer to run discovery again rather than saying results were lost.

Errors

404 NOT_FOUND — discoveryId does not exist or is not visible to the authenticated account.
409 BUYER_SETUP_REQUIRED — the buyer account has no confirmed, non-platform operator identity. The structured details are reason: "missing_operator_identity", readinessCheck: "operator_identity", setupStep: 1, and setupPage: "buyer_setup". Open Buyer Setup, confirm the operator domain and account scope, then retry. Apostra fails closed and does not substitute interchange.io as the buyer operator. If a legacy profile explicitly contains the platform domain, the same code is returned with details.reason: "platform_operator_not_allowed". Complete Buyer Setup with your organization’s operator domain; do not retry with the platform domain.

{
  "data": null,
  "error": {
    "code": "BUYER_SETUP_REQUIRED",
    "message": "Complete Buyer Setup step 1 by confirming your buyer operator identity before continuing.",
    "details": {
      "reason": "missing_operator_identity",
      "readinessCheck": "operator_identity",
      "setupStep": 1,
      "setupPage": "buyer_setup"
    }
  }
}

See Errors for the full error contract.

Discovery overview

Sessions and selection model

Add products

Add products to the selection

Remove products

Drop products from the selection

Apply proposal

Accept a seller’s full allocation

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Discovery overview

Add products

Remove products

Apply proposal

​Request

​Parameters

​Response

​Errors

​Related

Discovery overview

Add products

Remove products

Apply proposal

Request

Parameters

Response

Errors

Related