get_products task — discover advertising inventory in AdCP using natural language campaign briefs or structured filters. Returns matched products with pricing and formats.
Use this file to discover all available pages before exploring further.
Discover available advertising products based on campaign requirements using natural language briefs or structured filters.
Why this shape. Targeting, pricing, and curation are folded into one round-trip — the brief drives discovery, the publisher curates against it, and pricing_options carry firm prices the buyer commits against via pricing_option_id. We rejected a separate get_price_quote step between products and buy creation: it splits one expert decision into two underspecified ones and breaks the brief→curation contract. Iteration is buying_mode: "refine" with a typed change array — not a new task. → Design principle: the brief drives discovery.
You can also use structured filters instead of (or in addition to) a brief. In brief mode, filters act as hard constraints on top of the publisher’s curation — the brief describes intent, filters enforce requirements:
"brief", "wholesale", or "refine". "brief": publisher curates products from the brief. "wholesale": raw product feed access for buyer-directed targeting, brief must not be provided. "refine": iterate on products and proposals from a previous response using the refine array of change requests. v3 clients MUST include buying_mode. Sellers receiving requests from pre-v3 clients without buying_mode SHOULD default to "brief". Timing semantics:"wholesale" is a wholesale product feed read — sellers SHOULD return a synchronous response and MUST NOT route a "wholesale" request through the async/Submitted arm. Partial completion is signalled via incomplete[], not a task handoff. "brief" and "refine" MAY complete synchronously OR MAY return a Submitted envelope when curation requires upstream-system queries or HITL review the seller cannot complete inside time_budget. Buyers needing predictable fast wholesale product feed access MUST use "wholesale".
brief
string
Conditional
Natural language description of campaign requirements. Required when buying_mode is "brief". Must not be provided when buying_mode is "wholesale" or "refine".
Array of change requests for iterating on products and proposals. Required when buying_mode is "refine". Must not be provided when buying_mode is "brief" or "wholesale". See Refine array below.
brand
BrandRef
No
Brand reference (domain + optional brand_id). Resolved to full identity at execution time.
account
AccountRef
No
Account reference for account-specific pricing. Returns products with pricing from this account’s rate card.
Catalog of items the buyer wants to promote. The seller matches catalog items against its inventory and returns products where matches exist. Requires brand. See Catalog discovery below.
filters
Filters
No
Structured filters (see below)
fields
string[]
No
Specific product fields to include in the response for lightweight discovery. When requesting signal metadata, buyers SHOULD request included_signals for non-selectable bundled/planned signals, and signal_targeting_allowed, signal_targeting_options, and signal_targeting_rules for package-level signal selection.
property_list
PropertyListRef
No
[AdCP 3.0] Reference to a property list for filtering. See Property Lists
pagination
PaginationRequest
No
Cursor-based pagination for large product result sets and wholesale product feeds (see below)
if_wholesale_feed_version
string
No
Opaque wholesale_feed_version token from a prior get_products response. When provided, the seller compares against its current wholesale product feed version and MAY return unchanged: true (with products omitted) if nothing has changed. Versions are scoped to the (agent, account, filters, buying_mode, property_list, catalog) tuple. See Wholesale feed versioning.
if_pricing_version
string
No
Opaque pricing_version token from a prior response. MUST only be sent together with if_wholesale_feed_version. Evaluation order: if_wholesale_feed_version mismatch → full payload; if_wholesale_feed_version matches but if_pricing_version mismatches → full payload (so the buyer sees updated pricing_options); both match → seller MAY return unchanged: true. Sellers that don’t track pricing separately ignore this.
time_budget
Duration
No
Maximum time the buyer will commit to this request. The seller returns the best results achievable within this budget and does not start processes (human approvals, expensive external queries) that cannot complete in time. When omitted, the seller decides timing. Example: {"interval": 30, "unit": "seconds"}.
Property GovernanceThe property_list filter references a property list created via create_property_list on a property governance agent. Property lists define which publisher properties meet compliance requirements — COPPA-certified sites, sustainability-scored inventory, brand-safe publishers, etc.To use property list filtering:
Call get_adcp_capabilities on a property governance agent to discover available property_features
Create a property list via create_property_list with your feature requirements
Pass the resulting property_list_id to get_products to filter inventory
Filter for fixed-price vs auction products. Products with both pricing types can match either value, but the returned pricing_options array must include only options matching the requested pricing type so buyers can select deterministically from discovery.
format_ids
FormatID[]
Filter by specific format IDs
standard_formats_only
boolean
Only return products accepting IAB standard formats
min_exposures
integer
Minimum exposures needed for measurement validity
start_date
string
Campaign start date in ISO 8601 format (YYYY-MM-DD) for availability checks
end_date
string
Campaign end date in ISO 8601 format (YYYY-MM-DD) for availability checks
budget_range
object
Budget range to filter appropriate products (see Budget Range Object below)
countries
string[]
Filter by target countries using ISO 3166-1 alpha-2 codes (e.g., ["US", "CA", "GB"])
regions
string[]
Filter by region coverage using ISO 3166-2 codes (e.g., ["US-NY", "GB-SCT"]). Best for locally-bound inventory
metros
object[]
Filter by metro coverage. Each entry: { system, code } (e.g., [{ "system": "nielsen_dma", "code": "501" }])
channels
string[]
Filter by advertising channels (e.g., ["display", "ctv", "social", "streaming_audio"]). See Media Channel Taxonomy
video_placement_types
string[]
Filter video products by acceptable declared video placement types: instream, accompanying_content, interstitial, or standalone. Sellers should return only products they can satisfy with at least one requested type, and should exclude mixed, non-targetable bundles unless delivery can be constrained to the requested type. Uses IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names.
postal_areas
object[]
Filter by postal area coverage. Each entry: { system, values } (e.g., [{ "system": "us_zip", "values": ["10001"] }])
geo_proximity
object[]
Filter by proximity to geographic points. Each entry uses exactly one boundary method: radius, travel_time + transport_mode, or geometry
keywords
object[]
Filter by keyword relevance for search/retail media. Each entry: { keyword, match_type? }. match_type defaults to broad if omitted
signal_targeting
SignalTargeting[]
Discovery filter for products where the requested signals are buyer-selectable and jointly composable: available through inline signal_targeting_options and/or the seller’s get_signals feed for wholesale products that allow signal targeting but omit inline options, with signal_targeting_allowed: true, and compatible under the product’s signal_targeting_rules. Each entry uses signal_ref (signal_id is accepted only as a deprecated migration bridge) and may include targeting_mode: "include" or "exclude" to require support for any or none groups; omitted means "include". scope: "product" is seller-local exact option matching only, not a portable semantic identifier across products or sellers; buyers wanting portable discovery should use scope: "data_provider" or get_signals. included_signals and deprecated data_provider_signals metadata do not satisfy this filter because they cannot be selected on create_media_buy. This filter is not the buy-time request shape; package selection always uses packages[].targeting_overlay.signal_targeting_groups.
Filter to products that can meet the buyer’s performance standard requirements. Each entry specifies a metric, threshold, and vendor (e.g., “DoubleVerify for viewability at 70% MRC”). Products that cannot meet these thresholds or do not support the specified vendors are excluded.
Filter to products whose reporting_capabilities.available_metrics is a superset of these metrics — i.e., products that commit to reporting all listed metrics in delivery. Use for capability discovery (e.g., ["completed_views"] for a CTV CPCV buy). Sellers MUST silently exclude products that cannot meet the list — filter-not-fail; do not return an error. The product’s declared available_metrics becomes the binding reporting contract carried into the resulting media buy.
required_vendor_metrics
object[]
Filter to products whose reporting_capabilities.vendor_metrics covers vendor-defined metrics (proprietary attention, emissions, panel demographics, brand-lift surveys, etc.). Each entry pins vendor (BrandRef) and/or metric_id — at least one. Cross-vendor discovery (e.g., “any attention measurement”) is the buyer agent’s responsibility: resolve which vendors offer a category via the vendors’ brand.json records, then enumerate them as filter entries. Same filter-not-fail semantics as required_metrics.
get_products returns product placement data when the seller includes placements or the buyer asks for it through fields. Placement IDs are publisher-scoped. Product placements should reference the publisher’s public adagents.json placement declarations with {publisher_domain, placement_id} when a publisher declaration exists. Seller-private placement IDs, source/origin details, and delivery-system mappings must stay out of the response.Each returned placement may carry:
Field
Meaning
placement_id
Placement identifier in the publisher namespace. Buyers reference this with publisher_domain in creative_assignments[].placement_refs; legacy placement_ids strings are only unambiguous in single-publisher contexts.
publisher_domain
Domain whose adagents.json defines the publisher-referenced placement. New multi-publisher products SHOULD include it. When omitted on legacy products, buyers may interpret placement_id relative to the seller agent’s own publisher domain.
mode
targetable means the buyer may reference the publisher-scoped placement, for example in creative_assignments[].placement_refs. included means the placement is part of the product composition but not buyer-selectable.
video_placement_types
Declared video placement types for OLV and other video inventory, using the IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Concrete placements usually declare one value; aggregate placements may declare multiple.
format_ids / format_options
Placement-specific creative support. Product-level formats are the upper bound; placement-level formats narrow the effective accepted set for that placement and must not add formats the product does not accept.
Publishers can authorize sales agents for specific publisher placements using authorized_agents[].placement_ids or authorized_agents[].placement_tags in adagents.json. Sellers should only return publisher-referenced placements they are authorized to sell.Signal-targeting filter example:
The refine array is a list of change requests. Each entry declares a scope and what the buyer is asking for. At least one entry is required. The seller considers all entries together when composing the response, and replies to each via refinement_applied.Each entry is a discriminated union on scope:
"include" (default): return this product with updated pricing and data. "omit": exclude from the response. "more_like_this": find similar products (the original is also returned). When omitted, the seller treats the entry as "include".
ask
string
No
What the buyer is asking for. For "include": specific changes (e.g., "add 16:9 format"). For "more_like_this": what “similar” means (e.g., "same audience but video format"). Ignored when action is "omit".
"include" (default): return with updated allocations and pricing. "omit": exclude from the response. "finalize": request firm pricing and inventory hold (transitions a draft proposal to committed). When omitted, the seller treats the entry as "include".
ask
string
No
What the buyer is asking for (e.g., "shift more budget toward video", "reduce total by 10%"). Ignored when action is "omit".
When the seller receives a refine array, the response includes refinement_applied — an array matched by position. Each entry reports whether the ask was fulfilled:
Field
Type
Required
Description
scope
string
Yes
Echoes the scope ("request" / "product" / "proposal") from the corresponding refine entry.
product_id
string
Yes when scope is "product"
Echoes product_id from the corresponding refine entry.
proposal_id
string
Yes when scope is "proposal"
Echoes proposal_id from the corresponding refine entry.
status
string
Yes
"applied": ask fulfilled. "partial": partially fulfilled. "unable": could not fulfill.
notes
string
No
Seller explanation. Recommended when status is "partial" or "unable".
Pass a catalog to find advertising products that can promote your catalog items. The seller matches your catalog items against its inventory and returns products where matches exist. Supports all catalog types — a product catalog finds sponsored product slots, a job catalog finds job ad products, a flight catalog finds dynamic travel ads.The catalog field uses the same Catalog object used throughout AdCP. You can reference a synced catalog by catalog_id, provide inline items, or use selectors to filter:
Field
Type
Description
type
CatalogType
Catalog type (required) — product, job, hotel, flight, offering, etc.
catalog_id
string
Reference a synced catalog by ID
ids
string[]
Filter to specific item IDs
gtins
string[]
Filter by GTIN for cross-retailer matching (product type only)
tags
string[]
Filter by tags (OR logic)
category
string
Filter by category
query
string
Natural language filter
Products in the response include catalog_types (what catalog types they support) and catalog_match (which items matched).
Array of publisher entries, each with publisher_domain and either property_ids or property_tags
format_ids
FormatID[]
Supported creative format IDs
delivery_type
string
"guaranteed" or "non_guaranteed"
delivery_measurement
DeliveryMeasurement
(Optional) How delivery is measured (impressions, views, etc.)
pricing_options
PricingOption[]
Available pricing models (CPM, CPCV, etc.). Auction options may include floor_price and optional price_guidance. Bid-based auction models (CPM, vCPM, CPC, CPCV, CPV) may also include optional max_bid (boolean).
shows
CollectionSelector[]
(Optional) Collections available in this product. Each entry has publisher_domain and collection_ids. Buyers resolve full collection objects from the referenced adagents.json. See Collections and installments.
collection_targeting_allowed
boolean
(Optional, default: false) Whether buyers can target a subset of this product’s shows. When false, the product is a bundle.
data_provider_signals
DataProviderSignalSelector[]
(Optional, deprecated) Legacy/non-selectable metadata for data-provider signals already bundled into or associated with this product. New implementations should use included_signals.
included_signals
SignalListing[]
(Optional) Non-selectable signal metadata for signals already included in, bundled with, or planned into this product. These describe what the product is; buyers do not select them in package signal_targeting_groups. Data-provider and signal-source refs may be reference-only; product-local refs include inline name and value_type.
signal_targeting_allowed
boolean
(Optional, default: false) Whether this product has a package-level signal targeting surface. Editability is controlled by signal_targeting_rules; fixed/default-only products still set this to true when applied signal groups are echoed.
signal_targeting_options
ProductSignalTargetingOption[]
(Optional) Inline product-scoped signal options the buyer may select, or the seller may apply when fixed/default, through packages[].targeting_overlay.signal_targeting_groups. May include per-signal pricing_options; product-scoped prices are authoritative for this product. Data-provider and signal-source refs may be reference-only; product-local refs include inline name and value_type.
signal_targeting_rules
SignalTargetingRules
(Optional) Product-scoped composition rules for selectable signals, such as direct vs seller-planned resolution, optional, required, maximum, mutually exclusive, fixed selections, and group size limits. These limits belong on the product, not seller-wide get_adcp_capabilities, because products may be backed by different ad servers or seller planning layers. Fixed/default selections are applied by the seller and echoed on the resulting package state.
brief_relevance
string
Why this product matches the brief (when brief provided)
(Optional) Whether the buyer’s event setup is sufficient for this product’s optimization. Only present when the seller can evaluate the buyer’s account context.
Publishers may return proposals alongside products - structured media plans with budget allocations. See Proposals for details.
Field
Type
Description
proposal_id
string
Unique identifier for executing this proposal via create_media_buy
name
string
Human-readable name for the media plan
allocations
ProductAllocation[]
Budget allocations across products (percentages must sum to 100). Each allocation may include optional start_time and end_time for per-flight scheduling.
forecast
DeliveryForecast
Aggregate delivery forecast for the proposal. Contains forecast points with metric ranges. See Delivery Forecasts
total_budget_guidance
object
Optional min/recommended/max budget guidance
brief_alignment
string
How this proposal addresses the campaign brief
expires_at
string
ISO 8601 timestamp when this proposal expires
Each ForecastPoint is one forecast row. Composite slices are encoded by multiple dimensions[] items on the same point, such as placement x country. Sibling points are parallel rows, not nested children. Dimension order has no meaning; buyers normalize row identity from (forecast_range_unit, budget if present, product_id if present, dimensions sorted by kind). Buyers may compare rows at the same grain, but MUST NOT sum them unless the seller documents that the returned rows form a complete, non-overlapping partition. Standard delivery reporting verifies one-dimensional marginals, not exact cross-dimensional intersections.
For large product result sets and wholesale product feeds, use cursor-based pagination:
Request Parameter
Type
Description
pagination.max_results
integer
Maximum products per page (1-100, default: 50)
pagination.cursor
string
Cursor from previous response for next page
Response Field
Type
Description
pagination.has_more
boolean
Whether more products are available
pagination.cursor
string
Cursor to pass for the next page
pagination.total_count
integer
Total matching products (optional, not all backends support this)
Pagination is optional. When omitted, the server returns all results (or a server-chosen default page). When the response includes pagination.has_more: true, pass pagination.cursor in the next request to get the next page.
[AdCP 3.0] true if the agent filtered products based on the provided property_list. Absent or false if not provided or not supported.
catalog_applied
boolean
true if the seller filtered results based on the provided catalog. Absent or false if no catalog was provided or the seller does not support catalog matching.
Declares what the seller could not finish within the time_budget or due to internal limits. Each entry identifies a scope with a human-readable explanation. Absent when the response is fully complete. See incomplete array below.
filter_diagnostics
object
Optional non-fatal observability block describing how filters narrowed the candidate set — total_candidates plus per-filter excluded_by counts (keyed by filter name). Disambiguates “no inventory” from “your filter excluded everything” when the result list is empty or unexpectedly small. Counts only — never product names — to avoid leaking competitive intelligence. See filter_diagnostics below.
wholesale_feed_version
string
Opaque token representing the version of the wholesale product feed state used to compose this response. Sellers implementing conditional-fetch (if_wholesale_feed_version) MUST return this on every response so buyers can cache and probe later. Treat as opaque — no format, no ordering, no inspection. See Wholesale feed versioning.
pricing_version
string
Optional opaque token representing the version of the pricing layer, including product pricing_options and nested signal_targeting_options[].pricing_options. When the seller supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Sellers not separating these MAY omit pricing_version and use wholesale_feed_version for both.
cache_scope
string
"public" or "account". REQUIRED on every response (schema-enforced — the safety property of the two-layer cache depends on it). When the request had no account, MUST be "public". When the request had account, the seller declares either "public" (account prices off the rate card — buyer dedupes) or "account" (account-specific overrides). See Cache layering.
unchanged
boolean
Present and true ONLY when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the seller’s current version for the buyer’s cache_scope, in which case products[] MUST be omitted; wholesale_feed_version, cache_scope, and pricing_version (when used) MUST still be echoed. Sellers MUST NOT emit unchanged: false — absence of the field IS the “response carries products” signal (one shape per state). Buyers receiving unchanged: true MUST NOT mutate their local wholesale product mirror.
When the seller can attribute exclusions to specific filters, the response MAY include a filter_diagnostics block. This is observability — not error reporting; sellers still silently exclude unmatched products per the filter-not-fail convention. Buyers use this to triage empty/small results without depending on its presence. total_candidates and excluded_by are independently optional — sellers whose baseline candidate set size is sensitive MAY emit excluded_by without total_candidates.
Field
Type
Description
semantics
string
"only" (deterministic; counts products that would have been included if not for this filter alone — recommended for triage), "any" (counts products excluded by any filter; counts may overlap), or "approximate" (seller can’t cleanly attribute exclusions to a single filter). Buyers SHOULD inspect semantics before doing arithmetic on counts.
total_candidates
integer
Number of products considered before filters were applied. May be sampled or capped when the candidate pool is large. Optional.
excluded_by
object
Keys are filter property names from the request (required_metrics, required_geo_targeting, budget_range, etc.). Each value is { count, values?, notes? }. Only filters that meaningfully narrowed the set need appear.
excluded_by.<filter>.count
integer
Count of products excluded by this filter, interpreted per the parent semantics field.
excluded_by.<filter>.values
array
Optional list of the specific filter values that contributed to exclusions (e.g., ["completed_views"] for required_metrics). Items are strings or objects depending on filter shape; opaque without filter-specific knowledge.
When the seller cannot complete all work within the time_budget (or due to its own internal limits), the response includes incomplete — an array declaring what is missing. Buyers can use estimated_wait to decide whether to retry with a larger budget.
Field
Type
Required
Description
scope
string
Yes
"products": not all inventory sources were searched. "pricing": products returned but pricing is absent or unconfirmed. "forecast": products returned but forecast data is absent. "proposals": proposals were not generated or are incomplete. "wholesale_feed": in wholesale mode, full feed enumeration could not complete.
description
string
Yes
Human-readable explanation of what is missing and why.
estimated_wait
Duration
No
How much additional time would resolve this scope.
A buyer that just synced a seller’s wholesale product feed can ask “has anything changed since version X?” in one cheap call, regardless of feed size. Sellers return an opaque wholesale_feed_version on every response; buyers pass it back via if_wholesale_feed_version on the next call and the seller MAY short-circuit with unchanged: true — no products payload, no per-page diff. Patterned on HTTP ETag / If-None-Match.This is the seller-side wholesale product feed returned by get_products. It is not a sync_catalogs feed; sync_catalogs manages buyer-provided campaign input feeds on the seller account.Unchanged response example:Request:
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).
For pushed change tracking beyond conditional fetch, see specs/wholesale-feed-webhooks.md. Wholesale feed webhooks carry the changed product payload, pricing payload, removal tombstone, or bulk-change summary; get_products remains the repair and reconciliation read.
Sellers publish two notional layers: a public layer (the rate-card / structural view) and per-account overlays (custom deals, account-specific rate cards). The conditional-fetch path is layer-aware via cache_scope.Why this matters. A buyer mirroring wholesale products across N accounts at one seller doesn’t want to hold N copies of inventory that’s actually identical for every buyer. The public layer is the seller’s published rate card; most accounts at most sellers price off it directly. Premium custom deals are the exception.Two-layer cache.
wholesale_feed_version_account, the wholesale product feed payload as seen WITH this account ref, when cache_scope: "account" was returned
Behavior.
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.
Conditional fetch with if_wholesale_feed_version. Send the token paired with whichever scope it was returned in. The seller compares against the current version for that scope. If the buyer’s token belongs to an "account" scope but the seller responds with cache_scope: "public", that’s the downgrade signal — buyer drops the overlay.Webhook invalidation. Wholesale feed webhook events declare applies_to.scope on *.priced and *.updated payloads. Sellers MUST apply the same account/caller authorization predicate used by get_products buying_mode: "wholesale" when deciding which subscribers receive product webhooks:
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.”
See specs/wholesale-feed-webhooks.md §“Cache layering and event scoping” for the full webhook-side spec.See schema for complete field list: get-products-response.json
Declare a time budget when you need fast results and can accept partial data. The seller returns what it can within the budget and declares what is incomplete:
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}`); } } }}
A response with incomplete data — products are returned but some scopes are missing:
test=false
{ "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" } } ]}
import { testAgent } from '@adcp/sdk/testing';// Find products supporting both video and displayconst 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`);}
import { testAgent } from '@adcp/sdk/testing';// Find products within budget and date range for specific countries and channelsconst 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`);}
Use catalog with a brand to discover advertising products that can promote your catalog items. The seller matches your items against its inventory and returns products where matches exist:
import { testAgent } from '@adcp/sdk/testing';// Discover retail media products for specific catalog itemsconst 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'); }}
You can also use GTIN matching, reference a synced catalog, or discover products for other catalog types:
AdCP 3.0 - Property list filtering requires governance agent support.
Filter products to only those available on properties in your approved list:
import { testAgent } from '@adcp/sdk/testing';// Filter products by property list from governance agentconst 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)`); }}
Note: If property_list_applied is absent or false, the sales agent did not filter products. This can happen if:
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
Products have a property_targeting_allowed flag that affects filtering:
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
This allows publishers to offer run-of-network products that can’t be cherry-picked alongside flexible inventory that buyers can filter.See Property Targeting for more details and Property Governance for more on property lists.
After initial discovery, use buying_mode: "refine" to iterate on specific products and proposals. The refine array is a list of change requests — each entry declares a scope and what the buyer is asking for. The seller returns updated products with revised pricing and configurations, plus refinement_applied acknowledging each ask.See the Refinement guide for the full walkthrough: scope types, action semantics, seller responses, and common patterns. The parameter shape is defined in the Refine array section above.Minimal example:
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 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.
Most product searches complete immediately, but some scenarios require asynchronous processing. When this happens, you’ll receive a status other than completed and can track progress through webhooks or polling.
When the brief is unclear, the system asks for more details:
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"]}
Continue the conversation with the same context_id:
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": [...]}
Note: For the complete status list see Task Lifecycle.Most searches complete immediately. Async processing is only needed for complex scenarios or when the system needs your input.
