get_products

Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

​

Quick Start

import { testAgent } from '@adcp/sdk/testing';
import { GetProductsResponseSchema } from '@adcp/sdk';

const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Premium athletic footwear with innovative cushioning',
  brand: {
    domain: 'acmecorp.com'
  }
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

// Validate response against schema
const validated = GetProductsResponseSchema.parse(result.data);
console.log(`Found ${validated.products.length} products`);

// Access validated product fields
for (const product of validated.products) {
  console.log(`- ${product.name} (${product.delivery_type})`);
  console.log(`  Formats: ${product.format_ids.map(f => f.id).join(', ')}`);
}

​

Using Structured Filters

import { testAgent } from '@adcp/sdk/testing';

const result = await testAgent.getProducts({
  buying_mode: 'wholesale',
  brand: {
    domain: 'acmecorp.com'
  },
  filters: {
    channels: ['ctv'],
    delivery_type: 'guaranteed',
    standard_formats_only: true
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} guaranteed CTV products`);
}

​

Request Parameters

​

Filters Object

​

Placement fields

{
  "$schema": "/schemas/3.1.0-rc.4/media-buy/get-products-request.json",
  "buying_mode": "wholesale",
  "filters": {
    "signal_targeting": [
      {
        "signal_ref": {
          "scope": "data_provider",
          "data_provider_domain": "pinnacle-data.example",
          "signal_id": "auto_intenders"
        },
        "value_type": "binary",
        "value": true,
        "targeting_mode": "include"
      }
    ]
  },
  "fields": [
    "product_id",
    "name",
    "included_signals",
    "signal_targeting_allowed",
    "signal_targeting_options",
    "signal_targeting_rules",
    "pricing_options"
  ]
}

​

Currency filtering

{
  "$schema": "/schemas/3.1.0-rc.4/media-buy/get-products-request.json",
  "buying_mode": "wholesale",
  "filters": {
    "pricing_currencies": ["USD"]
  },
  "fields": ["product_id", "name", "pricing_options"]
}

​

Budget Range Object

​

Refine array

​

scope: “request”

​

scope: “product”

​

scope: “proposal”

​

refinement_applied (response)

​

Catalog discovery

​

Response

​

Products Array

​

Proposals Array (Optional)

​

Pagination

​

Response Metadata

​

filter_diagnostics

{
  "products": [],
  "filter_diagnostics": {
    "semantics": "only",
    "total_candidates": 47,
    "excluded_by": {
      "required_metrics": { "count": 31, "values": ["completed_views"] },
      "required_geo_targeting": { "count": 9 },
      "pricing_currencies": { "count": 3, "values": ["USD"] },
      "budget_range": { "count": 7 }
    }
  }
}

​

incomplete array

​

Wholesale feed versioning

{
  "$schema": "/schemas/3.1.0-rc.4/media-buy/get-products-request.json",
  "buying_mode": "wholesale",
  "if_wholesale_feed_version": "v2026-05-18T08:00:00Z-acme-rev412"
}

{
  "$schema": "/schemas/3.1.0-rc.4/media-buy/get-products-response.json",
  "status": "completed",
  "message": "Wholesale product feed unchanged since v2026-05-18T08:00:00Z-acme-rev412.",
  "context_id": "ctx-abc-789",
  "unchanged": true,
  "wholesale_feed_version": "v2026-05-18T08:00:00Z-acme-rev412",
  "pricing_version": "v2026-05-18T08:00:00Z-acme-rev412",
  "cache_scope": "public"
}

{
  "message": "Returning 50 of 312 products (wholesale feed version advanced).",
  "context_id": "ctx-abc-790",
  "wholesale_feed_version": "v2026-05-18T10:15:00Z-acme-rev415",
  "pricing_version": "v2026-05-18T10:15:00Z-acme-rev415",
  "cache_scope": "public",
  "products": [
    {
      "product_id": "prod_premium_ctv_us",
      "name": "Premium CTV — US",
      "description": "Run-of-network CTV inventory across premium publishers.",
      "publisher_properties": [{ "publisher_domain": "streamhaus.example.com", "property_ids": ["primetime_ctv"] }],
      "format_ids": [{ "id": "video_ctv_1080p_30s" }],
      "delivery_type": "guaranteed",
      "pricing_options": [
        { "pricing_option_id": "po_cpm_v2", "pricing_model": "cpm", "currency": "USD", "fixed_price": 18.50 }
      ]
    }
  ],
  "pagination": { "has_more": true, "cursor": "eyJvIjo1MH0=", "total_count": 312 }
}

• Tokens are opaque. No format, no ordering, no inspection.
• A returned wholesale_feed_version is scoped to the request parameters that produced it. Buyers MUST cache the version alongside the (account, filters, buying_mode, property_list, catalog) tuple used.
• pricing_version is an optional finer-grained token: when present, it changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Common for rate-card sweeps that don’t change product metadata.
• if_pricing_version requires if_wholesale_feed_version. Pricing has no structural baseline of its own. Sending if_pricing_version without if_wholesale_feed_version is a schema-level error. The seller’s evaluation is two-stage: wholesale feed mismatch returns the full payload (pricing is implicitly stale); wholesale feed match with pricing mismatch also returns the full payload (so the buyer sees updated pricing_options); both match → unchanged: true.
• filters canonicalization. Sellers MUST treat the filters object as canonicalized before hashing into the wholesale_feed_version keyspace: keys MUST be sorted lexicographically, omitted-and-default values MUST be treated identically (a missing delivery_type key is the same scope as delivery_type: null), array values MUST be sorted where the filter has set semantics (e.g., channels, format_ids, required_metrics) and preserved-order where the filter has sequence semantics (e.g., preferred_delivery_types). Buyers that pass equivalent-but-differently-shaped filter objects MUST receive the same wholesale_feed_version from the seller. This rule prevents silent stale-mirror bugs from key-order or default-elision differences between buyer SDKs. Forward-compat default: new filter fields added in 3.x minor versions MUST declare set-vs-sequence semantics in their schema (via x-canonicalization: set | sequence or equivalent prose); absent an explicit declaration, the rule defaults to set-semantics (sort before hashing). Sellers and SDKs that drift on this default produce cache misses that consumers can’t explain.
• Pagination interaction. wholesale_feed_version describes the wholesale product feed as a whole, not individual pages. Sellers MUST return wholesale_feed_version on every paginated page (not only the first) when they declare wholesale_feed_versioning.supported: true; sellers that do not declare versioning SHOULD do the same. When the wholesale feed mutates between pages, the new version surfaces on the next page and the buyer MUST restart pagination from cursor: null — the partial pages they’ve already received describe a stale version. Sellers MAY alternatively snapshot the feed at the start of pagination and serve all pages from that snapshot under the original version; either implementation is conformant as long as wholesale_feed_version on a given page is the version that page belongs to.
• unchanged: true and in-progress pagination. A buyer that is mid-pagination on cursor: X MAY send if_wholesale_feed_version matching the version their pages so far were drawn from. If the seller confirms unchanged: true, the response omits products[] and pagination envelope entirely; the buyer abandons their in-progress walk under that version with confidence that no further pages would have produced new data. Sellers MAY NOT use the conditional-fetch short-circuit to skip individual pages within an active pagination — unchanged is feed-versus-cached-version, not per-page.
• Pre-v3.1 sellers that ignore if_wholesale_feed_version simply return the full payload — semantically correct, just inefficient (same as the unchanged-server path in HTTP).

​

Cache layering

• Requests without account always return cache_scope: "public". Buyers cache under the public key.
• Requests with account return cache_scope: "public" OR "account" (seller MUST declare; no default).
  • "public": this account prices off the rate card. Buyer MAY dedupe — the version and payload are the same as the unauthenticated view. The buyer can serve subsequent requests for any account in "public" cache_scope from a single public-layer entry.
  • "account": this response carries account-specific overrides. Buyer caches under the account overlay key.
• Sellers MAY downgrade an account from "account" back to "public" by returning cache_scope: "public" on a request that previously got "account" — buyers SHOULD interpret this as “this account no longer has overrides” and drop their account overlay.

• applies_to: { scope: "public" } → invalidate the public-layer cache for the entity. All account overlays referencing that public version are also stale and SHOULD be refetched.
• applies_to: { scope: "account", account_ids: [...] } → invalidate only the named accounts’ overlays. The public layer is unaffected.
• applies_to: { scope: "account" } without account_ids → the seller is withholding the affected set; the per-subscriber scope filter routes the event only to subscribers whose principal is in the affected set. Receiving the event means “your overlay is stale.”

​

Common Scenarios

​

Time-budgeted discovery

import { testAgent } from '@adcp/sdk/testing';

const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'CTV and display for brand awareness',
  brand: {
    domain: 'acmecorp.com'
  },
  time_budget: {
    interval: 10,
    unit: 'seconds'
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} products`);

  if (result.data.incomplete) {
    for (const entry of result.data.incomplete) {
      console.log(`Incomplete: ${entry.scope} — ${entry.description}`);
      if (entry.estimated_wait) {
        console.log(`  Would resolve in ${entry.estimated_wait.interval} ${entry.estimated_wait.unit}`);
      }
    }
  }
}

{
  "products": [
    {
      "product_id": "prog-display-ros",
      "name": "Programmatic Display — Run of Site",
      "delivery_type": "non_guaranteed",
      "pricing_options": [{ "pricing_option_id": "cpm-ros", "pricing_model": "cpm", "currency": "USD", "fixed_price": 12.00 }]
    }
  ],
  "incomplete": [
    {
      "scope": "products",
      "description": "Premium inventory not searched — requires publisher approval",
      "estimated_wait": { "interval": 60, "unit": "minutes" }
    },
    {
      "scope": "forecast",
      "description": "Forecast model did not complete within budget",
      "estimated_wait": { "interval": 45, "unit": "seconds" }
    }
  ]
}

​

Wholesale Product Discovery

import { testAgent } from '@adcp/sdk/testing';

// wholesale mode: buyer applies their own audiences, no publisher curation
const result = await testAgent.getProducts({
  buying_mode: 'wholesale',
  brand: {
    domain: 'acmecorp.com'
  },
  filters: {
    delivery_type: 'non_guaranteed'
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} standard wholesale products`);
}

​

Multi-Format Discovery

import { testAgent } from '@adcp/sdk/testing';

// Find products supporting both video and display
const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Brand awareness campaign with video and display',
  brand: {
    domain: 'acmecorp.com'
  },
  filters: {
    channels: ['display', 'ctv']
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} products supporting video and display`);
}

​

Budget and Date Filtering

import { testAgent } from '@adcp/sdk/testing';

// Find products within budget and date range for specific countries and channels
const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Q2 campaign for athletic footwear in North America',
  brand: {
    domain: 'acmecorp.com'
  },
  filters: {
    start_date: '2025-04-01',
    end_date: '2025-06-30',
    budget_range: {
      min: 50000,
      max: 100000,
      currency: 'USD'
    },
    countries: ['US', 'CA'],
    channels: ['display', 'ctv', 'podcast'],
    delivery_type: 'guaranteed'
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} products for Q2 within budget`);
}

​

Property Tag Resolution

import { testAgent } from '@adcp/sdk/testing';

// Get products with property tags
const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Sports content',
  brand: {
    domain: 'acmecorp.com'
  }
});

if (result.success && result.data) {
  // Products with property_tags in publisher_properties represent large networks
  // Use get_adcp_capabilities to discover the agent's portfolio
  const productsWithTags = result.data.products.filter(p =>
    p.publisher_properties?.some(pub => pub.property_tags && pub.property_tags.length > 0)
  );
  console.log(`${productsWithTags.length} products use property tags (large networks)`);
}

​

Guaranteed Delivery Products

import { testAgent } from '@adcp/sdk/testing';

// Find guaranteed delivery products for measurement
const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Guaranteed delivery for lift study',
  brand: {
    domain: 'acmecorp.com'
  },
  filters: {
    delivery_type: 'guaranteed',
    min_exposures: 100000
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} guaranteed products with 100k+ exposures`);
}

​

Standard Formats Only

import { testAgent } from '@adcp/sdk/testing';

// Find products that only accept IAB standard formats
const result = await testAgent.getProducts({
  buying_mode: 'wholesale',
  brand: {
    domain: 'acmecorp.com'
  },
  filters: {
    standard_formats_only: true
  }
});

if (result.success && result.data) {
  console.log(`Found ${result.data.products.length} products with standard formats only`);
}

​

Catalog-driven discovery

import { testAgent } from '@adcp/sdk/testing';

// Discover retail media products for specific catalog items
const result = await testAgent.getProducts({
  buying_mode: 'wholesale',
  brand: {
    domain: 'acmecorp.com'
  },
  catalog: {
    type: 'product',
    tags: ['ketchup', 'organic'],
    category: 'food/condiments'
  },
  filters: {
    channels: ['retail_media']
  }
});

if (result.success && result.data) {
  if (result.data.catalog_applied) {
    console.log(`Found ${result.data.products.length} products with catalog matches`);
  } else {
    console.log('Seller does not support catalog matching');
  }
}

{
  "catalog": {
    "type": "product",
    "gtins": ["00013000006040", "00013000006057"]
  }
}

{
  "catalog": {
    "catalog_id": "gmc-primary",
    "type": "product"
  }
}

{
  "catalog": {
    "type": "job",
    "catalog_id": "chef-vacancies"
  }
}

​

Property List Filtering

import { testAgent } from '@adcp/sdk/testing';

// Filter products by property list from governance agent
const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Brand-safe inventory for family brand',
  brand: {
    domain: 'acmecorp.com'
  },
  property_list: {
    agent_url: 'https://governance.example.com',
    list_id: 'pl_brand_safe_2024'
  }
});

if (result.success && result.data) {
  // Check if filtering was actually applied
  if (result.data.property_list_applied) {
    console.log(`Found ${result.data.products.length} products on approved properties`);
  } else {
    console.log('Agent does not support property list filtering');
    console.log(`Found ${result.data.products.length} products (unfiltered)`);
  }
}

• The agent doesn’t support property governance features
• The agent couldn’t access the property list
• The property list had no effect on the available inventory

​

Property Targeting Behavior

• property_targeting_allowed: false (default): Product is “all or nothing” - excluded unless your list contains all of its properties
• property_targeting_allowed: true: Product is included if there’s any intersection between its properties and your list

​

Refinement

{
  "buying_mode": "refine",
  "refine": [
    { "scope": "request",                                             "ask": "more video, less display" },
    { "scope": "product",  "product_id":  "prod_premium_video",       "ask": "add 16:9 format option" },
    { "scope": "product",  "product_id":  "prod_display_run_of_site", "action": "omit" },
    { "scope": "proposal", "proposal_id": "prop_awareness_q2",        "ask": "reallocate display budget to video" }
  ],
  "filters": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "budget_range": { "min": 200000, "max": 200000, "currency": "USD" }
  }
}

• refine is only valid in refine mode. Requests that include this field in brief or wholesale mode are rejected with INVALID_REQUEST.
• Filters are absolute, not deltas. Always send the full filter set you want applied.
• Proposals are actionable through status. proposal_status: "draft" requires finalization before create; proposal_status: "committed" can be executed with create_media_buy(proposal_id) before expires_at; absent status is legacy ready-to-buy.
• Proposals are ephemeral. Proposals typically include an expires_at timestamp. After expiration, the seller returns PROPOSAL_EXPIRED.
• Product IDs are stable catalog identifiers. Custom products (is_custom: true) may have an expires_at timestamp, after which refinement returns PRODUCT_NOT_FOUND.

​

Error Handling

​

Authentication Comparison

import { testAgent, testAgentNoAuth } from '@adcp/sdk/testing';

// WITH authentication - full product results with pricing
const fullProducts = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Premium CTV inventory for brand awareness',
  brand: {
    domain: 'acmecorp.com'
  }
});

if (!fullProducts.success) {
  throw new Error(`Failed to get products: ${fullProducts.error}`);
}

console.log(`With auth: ${fullProducts.data.products.length} products`);
console.log(`First product pricing: ${fullProducts.data.products[0].pricing_options.length} options`);

// WITHOUT authentication - limited public product results
const publicProducts = await testAgentNoAuth.getProducts({
  buying_mode: 'brief',
  brief: 'Premium CTV inventory for brand awareness',
  brand: {
    domain: 'acmecorp.com'
  }
});

if (!publicProducts.success) {
  throw new Error(`Failed to get products: ${publicProducts.error}`);
}

console.log(`Without auth: ${publicProducts.data.products.length} products`);
console.log(`First product pricing: ${publicProducts.data.products[0].pricing_options?.length || 0} options`);

• Product Count: Authenticated access returns more products, including private/custom offerings
• Pricing Information: Only authenticated requests receive detailed pricing options (CPM, CPCV, etc.)
• Targeting Details: Custom targeting capabilities may be restricted to authenticated users
• Rate Limits: Unauthenticated requests have lower rate limits

​

Authentication Behavior

• Without credentials: Returns limited public product results, no pricing, no custom offerings
• With credentials: Returns complete product results with pricing and custom products

​

Asynchronous Operations

​

When Search Runs Asynchronously

• Complex searches: Searching across multiple inventory sources or custom curation
• Needs clarification: Your brief is vague and the system needs more information
• Custom products: Bespoke product packages that require human review

​

Async Status Flow

POST /api/mcp/call_tool

{
  "name": "get_products",
  "arguments": {
    "buying_mode": "brief",
    "brief": "CTV inventory for sports audience",
    "brand": { "domain": "acmecorp.com" }
  }
}

Response (200 OK):
{
  "status": "completed",
  "message": "Found 3 products matching your requirements",
  "products": [...]
}

Response (200 OK):
{
  "status": "input-required",
  "message": "I need a bit more information. What's your budget range and campaign duration?",
  "task_id": "task_789",
  "context_id": "ctx_123",
  "reason": "CLARIFICATION_NEEDED",
  "partial_results": [],
  "suggestions": ["$50K-$100K", "1 month", "Q1 2024"]
}

POST /api/mcp/continue

{
  "context_id": "ctx_123",
  "message": "Budget is $75K for a 3-week campaign in March"
}

Response (200 OK):
{
  "status": "completed",
  "message": "Perfect! Found 5 products within your budget",
  "products": [...]
}

POST /api/mcp/call_tool

{
  "name": "get_products",
  "arguments": {
    "buying_mode": "brief",
    "brief": "Premium inventory across all formats for luxury automotive brand",
    "brand": { "domain": "acmecorp.com" },
    "pushNotificationConfig": {
      "url": "https://buyer.com/webhooks/adcp/get_products",
      "authentication": {
        "schemes": ["Bearer"],
        "credentials": "secret_token_32_chars"
      }
    }
  }
}

Response (200 OK):
{
  "status": "working",
  "message": "Searching premium inventory across display, video, and audio",
  "task_id": "task_456",
  "context_id": "ctx_123",
  "percentage": 10,
  "current_step": "searching_inventory"
}

// Later, webhook POST to https://buyer.com/webhooks/adcp/get_products
{
  "task_id": "task_456",
  "task_type": "get_products",
  "status": "completed",
  "timestamp": "2025-01-22T10:30:00Z",
  "message": "Found 12 premium products across all formats",
  "result": {
    "products": [...]
  }
}

POST /api/a2a

{
  "message": {
    "role": "user",
    "parts": [{
      "kind": "data",
      "data": {
        "skill": "get_products",
        "parameters": {
          "buying_mode": "brief",
          "brief": "CTV inventory for sports audience",
          "brand": { "domain": "acmecorp.com" }
        }
      }
    }]
  }
}

Response (200 OK):
{
  "id": "task_123",
  "contextId": "ctx_456",
  "artifact": {
    "kind": "data",
    "data": {
      "products": [...]
    }
  },
  "status": {
    "state": "completed",
    "message": {
      "role": "agent",
      "parts": [{ "text": "Found 3 products matching your requirements" }]
    }
  }
}

// Initial response
{
  "id": "task_789",
  "contextId": "ctx_123",
  "status": {
    "state": "input-required",
    "message": {
      "role": "agent",
      "parts": [
        { "text": "I need a bit more information. What's your budget range and campaign duration?" },
        {
          "data": {
            "reason": "CLARIFICATION_NEEDED",
            "suggestions": ["$50K-$100K", "1 month", "Q1 2024"]
          }
        }
      ]
    }
  }
}

// Send follow-up
POST /api/a2a

{
  "contextId": "ctx_123",
  "message": {
    "role": "user",
    "parts": [{ "text": "Budget is $75K for a 3-week campaign in March" }]
  }
}

// SSE update: task completed
{
  "id": "task_789",
  "contextId": "ctx_123",
  "artifact": {
    "kind": "data",
    "data": { "products": [...] }
  },
  "status": {
    "state": "completed",
    "message": {
      "role": "agent",
      "parts": [{ "text": "Perfect! Found 5 products within your budget" }]
    }
  }
}

POST /api/a2a

{
  "message": {
    "role": "user",
    "parts": [{
      "kind": "data",
      "data": {
        "skill": "get_products",
        "parameters": {
          "buying_mode": "brief",
          "brief": "Premium inventory across all formats for luxury automotive brand",
          "brand": { "domain": "acmecorp.com" }
        }
      }
    }]
  },
  "pushNotificationConfig": {
    "url": "https://buyer.com/webhooks/a2a/get_products",
    "authentication": {
      "schemes": ["bearer"],
      "credentials": "secret_token_32_chars"
    }
  }
}

Response (200 OK):
{
  "id": "task_456",
  "contextId": "ctx_789",
  "status": {
    "state": "working",
    "message": {
      "role": "agent",
      "parts": [
        { "text": "Searching premium inventory across display, video, and audio" },
        {
          "data": {
            "percentage": 10,
            "current_step": "searching_inventory"
          }
        }
      ]
    }
  }
}

// Later, webhook POST to https://buyer.com/webhooks/a2a/get_products
{
  "id": "task_456",
  "contextId": "ctx_789",
  "artifact": {
    "kind": "data",
    "data": {
      "products": [...]
    }
  },
  "status": {
    "state": "completed",
    "message": {
      "role": "agent",
      "parts": [
        { "text": "Found 12 premium products across all formats" },
        {
          "data": {
            "products": [...]
          }
        }
      ]
    },
    "timestamp": "2025-01-22T10:30:00Z"
  }
}

​

Status Overview

​

Next Steps

1. Review Options: Compare products, pricing, and targeting capabilities
2. Create Media Buy: Use create_media_buy to execute campaign
3. Prepare Creatives: Use list_creative_formats to see format requirements
4. Upload Assets: Use sync_creatives to provide creative assets

​

Learn More

• Product Discovery Guide - Understanding briefs and products
• Pricing Models - CPM, CPCV, CPP explained
• Brief Expectations - How to write effective briefs
• Media Products - Product structure and fields