Discover products

curl --request POST \
  --url https://api.interchange.io/api/v2/buyer/discovery/discover-products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "advertiserId": 12345
}
'

import requests

url = "https://api.interchange.io/api/v2/buyer/discovery/discover-products"

payload = { "advertiserId": 12345 }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({advertiserId: 12345})
};

fetch('https://api.interchange.io/api/v2/buyer/discovery/discover-products', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "discoveryId": "abc123-def456-ghi789",
  "productGroups": [
    {
      "groupId": "<string>",
      "groupName": "<string>",
      "products": [
        {
          "productId": "prod_123",
          "name": "Premium CTV Inventory - Sports",
          "channel": "ctv",
          "channels": [
            "streaming_audio",
            "podcast"
          ],
          "inventoryType": "run_of_site",
          "formatTypes": [
            "video_hosted"
          ],
          "cpm": 12.5,
          "currency": "USD",
          "expiresAt": "2023-11-07T05:31:56Z",
          "salesAgentId": "<string>",
          "salesAgentName": "<string>",
          "storefrontId": "<string>",
          "storefrontName": "<string>",
          "supportedRoutingTypes": [],
          "description": "<string>",
          "deliveryType": "guaranteed",
          "briefRelevance": "<string>",
          "productCard": {
            "image": {
              "asset_type": "image",
              "url": "<string>",
              "width": 2,
              "height": 2,
              "format": "<string>",
              "alt_text": "<string>",
              "provenance": {
                "digital_source_type": "digital_capture",
                "ai_tool": {
                  "name": "<string>",
                  "version": "<string>",
                  "provider": "<string>"
                },
                "human_oversight": "none",
                "declared_by": {
                  "role": "creator",
                  "agent_url": "<string>"
                },
                "declared_at": "2023-11-07T05:31:56Z",
                "created_time": "2023-11-07T05:31:56Z",
                "c2pa": {
                  "manifest_url": "<string>"
                },
                "embedded_provenance": [
                  {
                    "method": "manifest_wrapper",
                    "provider": "<string>",
                    "standard": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "watermarks": [
                  {
                    "media_type": "audio",
                    "provider": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "c2pa_action": "c2pa.watermarked.bound",
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "disclosure": {
                  "required": true,
                  "jurisdictions": [
                    {
                      "country": "<string>",
                      "regulation": "<string>",
                      "region": "<string>",
                      "label_text": "<string>",
                      "render_guidance": {
                        "persistence": "continuous",
                        "min_duration_ms": 2,
                        "positions": [
                          "prominent"
                        ],
                        "ext": {}
                      }
                    }
                  ]
                },
                "verification": [
                  {
                    "verified_by": "<string>",
                    "result": "authentic",
                    "verified_time": "2023-11-07T05:31:56Z",
                    "confidence": 0.5,
                    "details_url": "<string>"
                  }
                ],
                "ext": {}
              }
            },
            "title": "<string>",
            "description": "<string>",
            "price_label": "<string>",
            "cta_label": "<string>"
          },
          "productCardDetailed": {
            "hero_image": {
              "asset_type": "image",
              "url": "<string>",
              "width": 2,
              "height": 2,
              "format": "<string>",
              "alt_text": "<string>",
              "provenance": {
                "digital_source_type": "digital_capture",
                "ai_tool": {
                  "name": "<string>",
                  "version": "<string>",
                  "provider": "<string>"
                },
                "human_oversight": "none",
                "declared_by": {
                  "role": "creator",
                  "agent_url": "<string>"
                },
                "declared_at": "2023-11-07T05:31:56Z",
                "created_time": "2023-11-07T05:31:56Z",
                "c2pa": {
                  "manifest_url": "<string>"
                },
                "embedded_provenance": [
                  {
                    "method": "manifest_wrapper",
                    "provider": "<string>",
                    "standard": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "watermarks": [
                  {
                    "media_type": "audio",
                    "provider": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "c2pa_action": "c2pa.watermarked.bound",
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "disclosure": {
                  "required": true,
                  "jurisdictions": [
                    {
                      "country": "<string>",
                      "regulation": "<string>",
                      "region": "<string>",
                      "label_text": "<string>",
                      "render_guidance": {
                        "persistence": "continuous",
                        "min_duration_ms": 2,
                        "positions": [
                          "prominent"
                        ],
                        "ext": {}
                      }
                    }
                  ]
                },
                "verification": [
                  {
                    "verified_by": "<string>",
                    "result": "authentic",
                    "verified_time": "2023-11-07T05:31:56Z",
                    "confidence": 0.5,
                    "details_url": "<string>"
                  }
                ],
                "ext": {}
              }
            },
            "carousel_images": [
              {
                "asset_type": "image",
                "url": "<string>",
                "width": 2,
                "height": 2,
                "format": "<string>",
                "alt_text": "<string>",
                "provenance": {
                  "digital_source_type": "digital_capture",
                  "ai_tool": {
                    "name": "<string>",
                    "version": "<string>",
                    "provider": "<string>"
                  },
                  "human_oversight": "none",
                  "declared_by": {
                    "role": "creator",
                    "agent_url": "<string>"
                  },
                  "declared_at": "2023-11-07T05:31:56Z",
                  "created_time": "2023-11-07T05:31:56Z",
                  "c2pa": {
                    "manifest_url": "<string>"
                  },
                  "embedded_provenance": [
                    {
                      "method": "manifest_wrapper",
                      "provider": "<string>",
                      "standard": "<string>",
                      "verify_agent": {
                        "agent_url": "<string>",
                        "feature_id": "<string>"
                      },
                      "embedded_at": "2023-11-07T05:31:56Z"
                    }
                  ],
                  "watermarks": [
                    {
                      "media_type": "audio",
                      "provider": "<string>",
                      "verify_agent": {
                        "agent_url": "<string>",
                        "feature_id": "<string>"
                      },
                      "c2pa_action": "c2pa.watermarked.bound",
                      "embedded_at": "2023-11-07T05:31:56Z"
                    }
                  ],
                  "disclosure": {
                    "required": true,
                    "jurisdictions": [
                      {
                        "country": "<string>",
                        "regulation": "<string>",
                        "region": "<string>",
                        "label_text": "<string>",
                        "render_guidance": {
                          "persistence": "continuous",
                          "min_duration_ms": 2,
                          "positions": [
                            "prominent"
                          ],
                          "ext": {}
                        }
                      }
                    ]
                  },
                  "verification": [
                    {
                      "verified_by": "<string>",
                      "result": "authentic",
                      "verified_time": "2023-11-07T05:31:56Z",
                      "confidence": 0.5,
                      "details_url": "<string>"
                    }
                  ],
                  "ext": {}
                }
              }
            ],
            "title": "<string>",
            "description": "<string>",
            "specifications": [
              {
                "label": "<string>",
                "value": "<string>"
              }
            ],
            "price_label": "<string>",
            "cta_label": "<string>"
          },
          "pricingOptions": [
            {
              "pricingOptionId": "<string>",
              "pricingModel": "<string>",
              "isFixed": true,
              "rate": 123,
              "floorPrice": 123,
              "fixedPrice": 123,
              "currency": "<string>",
              "priceGuidance": {
                "floor": 123,
                "p25": 123,
                "p50": 123,
                "p75": 123,
                "p90": 123
              }
            }
          ],
          "estimatedExposures": 0,
          "forecast": {},
          "bookability": "<string>",
          "publisherProperties": [
            {
              "publisherDomain": "<string>",
              "propertyType": "<string>",
              "name": "<string>",
              "selectionType": "<string>",
              "identifiers": [
                {}
              ]
            }
          ],
          "isSandbox": true,
          "formatOptions": [
            {
              "format_kind": "video_hosted",
              "format_option_id": "<string>",
              "display_name": "<string>",
              "params": {
                "containers": [
                  "mp4"
                ],
                "video_codecs": [
                  "h264"
                ],
                "audio_codecs": [
                  "aac"
                ]
              }
            }
          ]
        }
      ],
      "productCount": 4503599627370495,
      "totalProducts": 4503599627370495,
      "hasMoreProducts": true,
      "storefrontId": "<string>",
      "storefrontName": "<string>",
      "description": "<string>"
    }
  ],
  "totalGroups": 25,
  "hasMoreGroups": true,
  "summary": {
    "totalProducts": 150,
    "publishersCount": 25,
    "priceRange": {
      "min": 123,
      "max": 123,
      "avg": 123,
      "currency": "USD"
    }
  },
  "budgetContext": {
    "sessionBudget": 123,
    "allocatedBudget": 123,
    "remainingBudget": 123,
    "budgetWarning": "<string>"
  },
  "proposals": [
    {
      "proposalId": "<string>",
      "name": "<string>",
      "allocations": [
        {
          "productId": "<string>",
          "allocationPercentage": 50,
          "pricingOptionId": "<string>",
          "rationale": "<string>",
          "sequence": 0,
          "tags": [
            "<string>"
          ]
        }
      ],
      "description": "<string>",
      "briefAlignment": "<string>",
      "salesAgentId": "<string>",
      "salesAgentName": "<string>",
      "storefrontId": "<string>",
      "storefrontName": "<string>",
      "supportedRoutingTypes": [],
      "expiresAt": "<string>",
      "totalBudgetGuidance": {
        "min": 123,
        "recommended": 123,
        "max": 123,
        "currency": "<string>"
      }
    }
  ],
  "incompleteAgents": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "waitSeconds": 4503599627370496,
      "storefronts": [
        {
          "storefrontId": "<string>",
          "storefrontName": "<string>"
        }
      ],
      "responseTimeMs": 4503599627370495,
      "incompleteScopes": [
        {
          "description": "<string>",
          "estimatedWaitSeconds": 4503599627370496
        }
      ]
    }
  ],
  "connectionIssues": [
    {
      "providerType": "meta",
      "storefrontId": "<string>",
      "storefrontName": "<string>"
    }
  ],
  "retryWithLongerWaitAvailable": true,
  "agentResults": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "success": true,
      "productCount": 4503599627370495,
      "responseTimeMs": 4503599627370495,
      "timedOut": true,
      "storefronts": [
        {
          "storefrontId": "<string>",
          "storefrontName": "<string>"
        }
      ],
      "error": "<string>",
      "skipReason": "<string>",
      "incomplete": [
        {
          "description": "<string>",
          "estimated_wait": {
            "interval": 1
          }
        }
      ],
      "rawResponseData": "<unknown>",
      "debugLogs": [
        {
          "timestamp": "<string>",
          "type": "<string>",
          "message": "<string>",
          "request": {},
          "response": {}
        }
      ]
    }
  ],
  "refinementApplied": [
    {
      "id": "<string>",
      "notes": "<string>"
    }
  ],
  "revision": 3,
  "resultsComplete": false,
  "pendingAgents": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "storefronts": [
        {
          "storefrontId": "<string>",
          "storefrontName": "<string>"
        }
      ]
    }
  ],
  "progress": {
    "respondedStorefrontCount": 4503599627370495,
    "totalStorefrontCount": 4503599627370495,
    "waitSeconds": 4503599627370496
  },
  "diagnostics": {
    "trace": {
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "spanId": "00f067aa0ba902b7",
      "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
    }
  },
  "guidance": "2 seller(s) still working — call browse_discovery with sinceRevision: 3 for newly landed results."
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

POST

discovery

discover-products

Discover products

curl --request POST \
  --url https://api.interchange.io/api/v2/buyer/discovery/discover-products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "advertiserId": 12345
}
'

import requests

url = "https://api.interchange.io/api/v2/buyer/discovery/discover-products"

payload = { "advertiserId": 12345 }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({advertiserId: 12345})
};

fetch('https://api.interchange.io/api/v2/buyer/discovery/discover-products', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "discoveryId": "abc123-def456-ghi789",
  "productGroups": [
    {
      "groupId": "<string>",
      "groupName": "<string>",
      "products": [
        {
          "productId": "prod_123",
          "name": "Premium CTV Inventory - Sports",
          "channel": "ctv",
          "channels": [
            "streaming_audio",
            "podcast"
          ],
          "inventoryType": "run_of_site",
          "formatTypes": [
            "video_hosted"
          ],
          "cpm": 12.5,
          "currency": "USD",
          "expiresAt": "2023-11-07T05:31:56Z",
          "salesAgentId": "<string>",
          "salesAgentName": "<string>",
          "storefrontId": "<string>",
          "storefrontName": "<string>",
          "supportedRoutingTypes": [],
          "description": "<string>",
          "deliveryType": "guaranteed",
          "briefRelevance": "<string>",
          "productCard": {
            "image": {
              "asset_type": "image",
              "url": "<string>",
              "width": 2,
              "height": 2,
              "format": "<string>",
              "alt_text": "<string>",
              "provenance": {
                "digital_source_type": "digital_capture",
                "ai_tool": {
                  "name": "<string>",
                  "version": "<string>",
                  "provider": "<string>"
                },
                "human_oversight": "none",
                "declared_by": {
                  "role": "creator",
                  "agent_url": "<string>"
                },
                "declared_at": "2023-11-07T05:31:56Z",
                "created_time": "2023-11-07T05:31:56Z",
                "c2pa": {
                  "manifest_url": "<string>"
                },
                "embedded_provenance": [
                  {
                    "method": "manifest_wrapper",
                    "provider": "<string>",
                    "standard": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "watermarks": [
                  {
                    "media_type": "audio",
                    "provider": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "c2pa_action": "c2pa.watermarked.bound",
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "disclosure": {
                  "required": true,
                  "jurisdictions": [
                    {
                      "country": "<string>",
                      "regulation": "<string>",
                      "region": "<string>",
                      "label_text": "<string>",
                      "render_guidance": {
                        "persistence": "continuous",
                        "min_duration_ms": 2,
                        "positions": [
                          "prominent"
                        ],
                        "ext": {}
                      }
                    }
                  ]
                },
                "verification": [
                  {
                    "verified_by": "<string>",
                    "result": "authentic",
                    "verified_time": "2023-11-07T05:31:56Z",
                    "confidence": 0.5,
                    "details_url": "<string>"
                  }
                ],
                "ext": {}
              }
            },
            "title": "<string>",
            "description": "<string>",
            "price_label": "<string>",
            "cta_label": "<string>"
          },
          "productCardDetailed": {
            "hero_image": {
              "asset_type": "image",
              "url": "<string>",
              "width": 2,
              "height": 2,
              "format": "<string>",
              "alt_text": "<string>",
              "provenance": {
                "digital_source_type": "digital_capture",
                "ai_tool": {
                  "name": "<string>",
                  "version": "<string>",
                  "provider": "<string>"
                },
                "human_oversight": "none",
                "declared_by": {
                  "role": "creator",
                  "agent_url": "<string>"
                },
                "declared_at": "2023-11-07T05:31:56Z",
                "created_time": "2023-11-07T05:31:56Z",
                "c2pa": {
                  "manifest_url": "<string>"
                },
                "embedded_provenance": [
                  {
                    "method": "manifest_wrapper",
                    "provider": "<string>",
                    "standard": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "watermarks": [
                  {
                    "media_type": "audio",
                    "provider": "<string>",
                    "verify_agent": {
                      "agent_url": "<string>",
                      "feature_id": "<string>"
                    },
                    "c2pa_action": "c2pa.watermarked.bound",
                    "embedded_at": "2023-11-07T05:31:56Z"
                  }
                ],
                "disclosure": {
                  "required": true,
                  "jurisdictions": [
                    {
                      "country": "<string>",
                      "regulation": "<string>",
                      "region": "<string>",
                      "label_text": "<string>",
                      "render_guidance": {
                        "persistence": "continuous",
                        "min_duration_ms": 2,
                        "positions": [
                          "prominent"
                        ],
                        "ext": {}
                      }
                    }
                  ]
                },
                "verification": [
                  {
                    "verified_by": "<string>",
                    "result": "authentic",
                    "verified_time": "2023-11-07T05:31:56Z",
                    "confidence": 0.5,
                    "details_url": "<string>"
                  }
                ],
                "ext": {}
              }
            },
            "carousel_images": [
              {
                "asset_type": "image",
                "url": "<string>",
                "width": 2,
                "height": 2,
                "format": "<string>",
                "alt_text": "<string>",
                "provenance": {
                  "digital_source_type": "digital_capture",
                  "ai_tool": {
                    "name": "<string>",
                    "version": "<string>",
                    "provider": "<string>"
                  },
                  "human_oversight": "none",
                  "declared_by": {
                    "role": "creator",
                    "agent_url": "<string>"
                  },
                  "declared_at": "2023-11-07T05:31:56Z",
                  "created_time": "2023-11-07T05:31:56Z",
                  "c2pa": {
                    "manifest_url": "<string>"
                  },
                  "embedded_provenance": [
                    {
                      "method": "manifest_wrapper",
                      "provider": "<string>",
                      "standard": "<string>",
                      "verify_agent": {
                        "agent_url": "<string>",
                        "feature_id": "<string>"
                      },
                      "embedded_at": "2023-11-07T05:31:56Z"
                    }
                  ],
                  "watermarks": [
                    {
                      "media_type": "audio",
                      "provider": "<string>",
                      "verify_agent": {
                        "agent_url": "<string>",
                        "feature_id": "<string>"
                      },
                      "c2pa_action": "c2pa.watermarked.bound",
                      "embedded_at": "2023-11-07T05:31:56Z"
                    }
                  ],
                  "disclosure": {
                    "required": true,
                    "jurisdictions": [
                      {
                        "country": "<string>",
                        "regulation": "<string>",
                        "region": "<string>",
                        "label_text": "<string>",
                        "render_guidance": {
                          "persistence": "continuous",
                          "min_duration_ms": 2,
                          "positions": [
                            "prominent"
                          ],
                          "ext": {}
                        }
                      }
                    ]
                  },
                  "verification": [
                    {
                      "verified_by": "<string>",
                      "result": "authentic",
                      "verified_time": "2023-11-07T05:31:56Z",
                      "confidence": 0.5,
                      "details_url": "<string>"
                    }
                  ],
                  "ext": {}
                }
              }
            ],
            "title": "<string>",
            "description": "<string>",
            "specifications": [
              {
                "label": "<string>",
                "value": "<string>"
              }
            ],
            "price_label": "<string>",
            "cta_label": "<string>"
          },
          "pricingOptions": [
            {
              "pricingOptionId": "<string>",
              "pricingModel": "<string>",
              "isFixed": true,
              "rate": 123,
              "floorPrice": 123,
              "fixedPrice": 123,
              "currency": "<string>",
              "priceGuidance": {
                "floor": 123,
                "p25": 123,
                "p50": 123,
                "p75": 123,
                "p90": 123
              }
            }
          ],
          "estimatedExposures": 0,
          "forecast": {},
          "bookability": "<string>",
          "publisherProperties": [
            {
              "publisherDomain": "<string>",
              "propertyType": "<string>",
              "name": "<string>",
              "selectionType": "<string>",
              "identifiers": [
                {}
              ]
            }
          ],
          "isSandbox": true,
          "formatOptions": [
            {
              "format_kind": "video_hosted",
              "format_option_id": "<string>",
              "display_name": "<string>",
              "params": {
                "containers": [
                  "mp4"
                ],
                "video_codecs": [
                  "h264"
                ],
                "audio_codecs": [
                  "aac"
                ]
              }
            }
          ]
        }
      ],
      "productCount": 4503599627370495,
      "totalProducts": 4503599627370495,
      "hasMoreProducts": true,
      "storefrontId": "<string>",
      "storefrontName": "<string>",
      "description": "<string>"
    }
  ],
  "totalGroups": 25,
  "hasMoreGroups": true,
  "summary": {
    "totalProducts": 150,
    "publishersCount": 25,
    "priceRange": {
      "min": 123,
      "max": 123,
      "avg": 123,
      "currency": "USD"
    }
  },
  "budgetContext": {
    "sessionBudget": 123,
    "allocatedBudget": 123,
    "remainingBudget": 123,
    "budgetWarning": "<string>"
  },
  "proposals": [
    {
      "proposalId": "<string>",
      "name": "<string>",
      "allocations": [
        {
          "productId": "<string>",
          "allocationPercentage": 50,
          "pricingOptionId": "<string>",
          "rationale": "<string>",
          "sequence": 0,
          "tags": [
            "<string>"
          ]
        }
      ],
      "description": "<string>",
      "briefAlignment": "<string>",
      "salesAgentId": "<string>",
      "salesAgentName": "<string>",
      "storefrontId": "<string>",
      "storefrontName": "<string>",
      "supportedRoutingTypes": [],
      "expiresAt": "<string>",
      "totalBudgetGuidance": {
        "min": 123,
        "recommended": 123,
        "max": 123,
        "currency": "<string>"
      }
    }
  ],
  "incompleteAgents": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "waitSeconds": 4503599627370496,
      "storefronts": [
        {
          "storefrontId": "<string>",
          "storefrontName": "<string>"
        }
      ],
      "responseTimeMs": 4503599627370495,
      "incompleteScopes": [
        {
          "description": "<string>",
          "estimatedWaitSeconds": 4503599627370496
        }
      ]
    }
  ],
  "connectionIssues": [
    {
      "providerType": "meta",
      "storefrontId": "<string>",
      "storefrontName": "<string>"
    }
  ],
  "retryWithLongerWaitAvailable": true,
  "agentResults": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "success": true,
      "productCount": 4503599627370495,
      "responseTimeMs": 4503599627370495,
      "timedOut": true,
      "storefronts": [
        {
          "storefrontId": "<string>",
          "storefrontName": "<string>"
        }
      ],
      "error": "<string>",
      "skipReason": "<string>",
      "incomplete": [
        {
          "description": "<string>",
          "estimated_wait": {
            "interval": 1
          }
        }
      ],
      "rawResponseData": "<unknown>",
      "debugLogs": [
        {
          "timestamp": "<string>",
          "type": "<string>",
          "message": "<string>",
          "request": {},
          "response": {}
        }
      ]
    }
  ],
  "refinementApplied": [
    {
      "id": "<string>",
      "notes": "<string>"
    }
  ],
  "revision": 3,
  "resultsComplete": false,
  "pendingAgents": [
    {
      "agentId": "<string>",
      "agentName": "<string>",
      "storefronts": [
        {
          "storefrontId": "<string>",
          "storefrontName": "<string>"
        }
      ]
    }
  ],
  "progress": {
    "respondedStorefrontCount": 4503599627370495,
    "totalStorefrontCount": 4503599627370495,
    "waitSeconds": 4503599627370496
  },
  "diagnostics": {
    "trace": {
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "spanId": "00f067aa0ba902b7",
      "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
    }
  },
  "guidance": "2 seller(s) still working — call browse_discovery with sinceRevision: 3 for newly landed results."
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key or access token

Body

application/json

Request body for discovering products with optional auto-session creation

advertiserId

integer

required

Advertiser ID used to resolve BrandReference

Required range: 1 <= x <= 9007199254740991

Example:

12345

discoveryId

string

Existing discovery ID. If not provided, a new discovery session is created.

Example:

"abc123-def456-ghi789"

campaignId

string

Campaign ID to seed discovery from. The campaign brief, flight dates, and budget are used as defaults (explicit request values take precedence).

Example:

"campaign_ea5e33dd-d65b-44c7-a3e8-8e1db1d137b4"

proposalCode

string

Storefront-issued proposal code (e.g. "PRP-XK4A29"). When set, the server short-circuits discovery and returns the seller's saved snapshot for this code. Caller's resolved operator must match the proposal's assigned operator. Other discovery filters (brief, budget, channels, refine, etc.) are ignored.

Example:

"PRP-XK4A29"

channels

enum<string>[]

Channels to search (defaults to ["display", "olv", "ctv", "social"]). Accepts any AdCP MediaChannel value. "video" is an alias for "olv"; "audio" is an alias for "streaming_audio".

Available options:

display

Example:

["ctv", "display"]

countries

string[]

Countries to target (defaults to brand agent countries if not specified)

Maximum array length: 250

Pattern: ^[A-Z]{2}$

Example:

["US", "CA"]

brief

string

Natural language context for product search

Maximum string length: 5000

Example:

"Looking for premium video inventory targeting tech enthusiasts"

budget

number

Budget for the discovery

Required range: x > 0

Example:

50000

flightDates

object

Optional flight dates for availability filtering

Show child attributes

publisherDomain

string

Filter products by publisher domain (exact domain component match)

Minimum string length: 1

Example:

"hulu"

pricingModel

enum<string>

Filter products by pricing model

Available options:

cpm,

vcpm,

cpc,

cpcv,

cpv,

cpp,

cpa,

flat_rate,

time

Example:

"cpm"

waitMode

enum<string>

default:quick

quick waits up to 30 seconds per storefront agent and returns partial results if slow agents miss the window. long waits up to 210 seconds per storefront agent; ask the user before using it.

Available options:

quick,

long

Example:

"quick"

waitSeconds

integer

Optional explicit per-storefront wait in seconds, max 210. Overrides waitMode. Ask the user before setting this above 30.

Required range: 1 <= x <= 210

Example:

120

progressive

boolean

Progressive delivery: return a fast first wave of already-answered sellers with resultsComplete: false and pendingAgents, while remaining sellers keep landing in the background. Follow with browse_discovery using sinceRevision until resultsComplete is true; if it is still false after roughly the wait budget (or pendingAgents stops shrinking), treat remaining pendingAgents like incompleteAgents and proceed with what you have. waitMode/waitSeconds still cap each seller's own deadline. A repeat of a recent identical query may return complete immediately. Ignored when refine or screening is present — those responses are terminal-only on the legacy Discover surface; use buyer get_products for progressive screened replacement pages.

Example:

true

storefrontIds

integer[]

Filter discovery to these storefronts. Highly encouraged when the buyer wants results scoped to specific sellers — pass the IDs returned by list_storefronts. Combined with storefrontNames using OR logic. An empty array or omitted field both mean "no request-level filter" — if a campaignId is also provided and the campaign was created with storefrontIds, the campaign-level value is used in that case.

Maximum array length: 50

Required range: 1 <= x <= 9007199254740991

Example:

[42, 57]

storefrontNames

string[]

Filter discovery to storefronts whose name matches one of these values (case-insensitive substring match). Use when the buyer mentions a seller by name. Combined with storefrontIds using OR logic. An empty array or omitted field both mean "no request-level filter" — campaign-level pinning is used in that case if available.

Maximum array length: 50

Maximum string length: 255

Example:

["Acme", "Acme Exchange"]

groupLimit

integer

default:10

Maximum number of product groups to return (default: 10, max: 10)

Required range: 1 <= x <= 10

Example:

10

groupOffset

integer

default:0

Number of groups to skip for pagination

Required range: 0 <= x <= 9007199254740991

Example:

0

productsPerGroup

integer

default:10

Maximum products to return per group (default: 10, max: 15)

Required range: 1 <= x <= 15

Example:

10

productOffset

integer

default:0

Number of products to skip within each group (default: 0, max: 1000)

Required range: 0 <= x <= 1000

Example:

5

debug

boolean

When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting

screening

object

Deprecated alias for evaluation. Discover delegates these instructions to the shared proposal-evaluation engine.

Show child attributes

evaluation

object

Optional managed proposal evaluation: disposition, buyer-side enrichment, bounded seller refinement, and optional comparative ranking.

Show child attributes

refine

object[]

Refinement instructions for iterating on previous discovery results. When provided, discoveryId is required.

Required array length: 1 - 100 elements

A refinement instruction for iterating on discovery results. Scoped to the overall request, a specific product, or a specific proposal.

Option 1
Option 2
Option 3

Show child attributes

Response

Discover products

Response from discovering products

discoveryId

string

required

Discovery ID

Example:

"abc123-def456-ghi789"

productGroups

object[]

required

Products grouped by publisher

Show child attributes

totalGroups

integer

required

Total number of product groups available

Required range: 0 <= x <= 9007199254740991

Example:

25

hasMoreGroups

boolean

required

Whether more groups are available beyond those shown

summary

object

required

Summary statistics for discovered products

Show child attributes

budgetContext

object

Budget context if budget was provided

Show child attributes

proposals

object[]

Recommended media plans from sales agents (ADCP v3). Each proposal explains WHY certain products are recommended together and how budget should be allocated.

Show child attributes

incompleteAgents

object[]

Storefront agents that timed out or returned ADCP incomplete scopes under the requested wait window. Present without debug=true so callers can offer a longer retry without exposing raw agent logs.

Show child attributes

connectionIssues

object[]

Adapter connections that require re-authentication. When present, one or more storefronts were skipped because their OAuth credentials have expired. Go to Settings > Connections to reconnect, then retry.

Show child attributes

retryWithLongerWaitAvailable

boolean

True when at least one storefront timed out or returned ADCP incomplete scopes and the request used less than the maximum interactive wait window.

agentResults

object[]

Per-agent debug info. Only present when debug=true; includes timing so callers can decide whether to retry with a longer wait.

Show child attributes

refinementApplied

object[]

Seller's response to each refinement instruction, matched by position to the request's refine array. Only present when refine was provided.

Show child attributes

revision

integer

Progressive delivery: monotonic snapshot revision. Present on progressive responses and sinceRevision polls; pass it back as sinceRevision to fetch only newly landed seller groups.

Required range: 0 <= x <= 9007199254740991

Example:

3

resultsComplete

boolean

Progressive delivery: false while sellers are still answering in the background. Poll browse_discovery with sinceRevision until true.

Example:

false

pendingAgents

object[]

Progressive delivery: sellers still in flight (not yet answered). Distinct from incompleteAgents, which timed out or answered partially at the final revision.

Show child attributes

progress

object

Progressive delivery: authoritative storefront response counts, independent of result-group pagination and sinceRevision delta pages.

Show child attributes

diagnostics

object

Advanced support diagnostics. Returned only to elevated/admin contexts and intended for internal troubleshooting.

Show child attributes

guidance

string

Human-readable next-step guidance. On progressive responses this spells out the exact continuation call (browse with sinceRevision); on empty results it explains what was queried and suggests adding a brief/brand URL or broadening filters.

Example:

"2 seller(s) still working — call browse_discovery with sinceRevision: 3 for newly landed results."

⌘I