https://adcontextprotocol.org/schemas/v3/signals/get-signals-request.json
Response Schema: https://adcontextprotocol.org/schemas/v3/signals/get-signals-response.json
The get_signals task returns both signal metadata and real-time deployment status across platforms, allowing agents to understand availability and guide the activation process.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
signal_spec | string | Conditional | Natural language description of the desired signals. Required unless signal_ids is provided. |
signal_ids | SignalID[] | Conditional | Specific signals to look up by data provider and ID. Required unless signal_spec is provided. |
account | AccountRef | No | Account for this request. When provided, the signals agent returns per-account pricing options if configured. |
destinations | Destination[] | No | Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. See Destination Object below. |
countries | string[] | No | Countries where signals will be used (ISO 3166-1 alpha-2 codes) |
filters | Filters | No | Filters to refine results (see Filters Object below) |
max_results | number | No | Maximum number of results to return |
pagination | object | No | Pagination: cursor (opaque cursor from previous response) for paging through large result sets |
Destination Object
Each deployment target uses atype field to discriminate between platform-based and agent-based deployments:
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Discriminator: “platform” for DSPs, “agent” for sales agents |
platform | string | Conditional* | Platform identifier (e.g., ‘the-trade-desk’, ‘amazon-dsp’). Required when type=“platform” |
agent_url | string (URI) | Conditional* | URL identifying the sales agent. Required when type=“agent” |
account | string | No | Account identifier on the platform or agent |
platform is required when type="platform", agent_url is required when type="agent".
Destination filtering: Signals are returned if they are available on any of the requested destinations (OR semantics). Destinations where a signal is not available are omitted from that signal’s response deployments array. A PARTIAL_COVERAGE warning may be included when some destinations don’t support the signal.
Activation Keys: If the authenticated caller has access to any of the destinations in the request, the signal agent will include activation_key fields in the response for those deployments (when is_live: true).
Permission Model: The signal agent determines key inclusion based on the caller’s authentication and authorization. For example:
- A sales agent receives keys for deployments matching its
agent_url - A buyer with credentials for multiple DSP platforms receives keys for all those deployments
- Access is determined by the signal agent’s permission system, not by flags in the request
Filters Object
| Parameter | Type | Required | Description |
|---|---|---|---|
catalog_types | string[] | No | Filter by catalog type (“marketplace”, “custom”, “owned”) |
data_providers | string[] | No | Filter by specific data providers |
max_cpm | number | No | Maximum CPM price filter. Excludes signals where all CPM-based pricing options exceed this value. Signals without CPM-based pricing options are not affected by this filter. |
min_coverage_percentage | number | No | Minimum coverage requirement |
Response Structure
All AdCP responses include:- message: Human-readable summary of the operation result
- context_id: Session continuity identifier for follow-up requests
- data: Task-specific payload (see Response Data below)
- MCP: Returns complete response as flat JSON
- A2A: Returns as artifacts with message in text part, data in data part
Response Data
Field Descriptions
- signals: Array of matching signals
- signal_agent_segment_id: Unique identifier for the signal
- name: Human-readable signal name
- description: Detailed signal description
- signal_type: Type of signal (marketplace, custom, owned)
- data_provider: Name of the data provider
- coverage_percentage: Percentage of audience coverage
- deployments: Array of destination deployments
- agent_url: URL identifying the destination agent
- account: Account identifier if applicable
- is_live: Whether signal is currently active on this deployment
- activation_key: The key to use for targeting (see Activation Key below). Only present when
is_live=trueand the authenticated caller has access to this deployment. - estimated_activation_duration_minutes: Time to activate if not live
- pricing_options: Array of pricing options for this signal. Pass the selected
pricing_option_idinreport_usagefor billing verification.- pricing_option_id: Unique identifier for this pricing option
- model: Pricing model —
cpm,percent_of_media, orflat_fee model: "cpm"—cpm(number, cost per thousand impressions),currency(ISO 4217)model: "percent_of_media"—percent(0–100),currency(ISO 4217),max_cpm(optional CPM cap: effective charge =min(percent × media_spend_per_mille, max_cpm))model: "flat_fee"—amount(fixed charge),currency(ISO 4217),period(monthly,quarterly,annual, orcampaign)
pricing_option_id in report_usage for billing verification. If a signal offers multiple models (e.g., CPM and flat fee), choose based on your expected delivery volume and campaign structure.
Activation Key Object
The activation key represents how to use the signal on a deployment target. It can be either a segment ID or a key-value pair: Segment ID format:Protocol-Specific Examples
The AdCP payload is identical across protocols. Only the request/response wrapper differs.MCP Request - Sales Agent Requesting Signals
A sales agent querying for signals. Because the authenticated caller is wonderstruck.salesagents.com, the signal agent will include activation keys in the response:MCP Response - With Activation Key
Because the authenticated caller matches the deployment target, the response includes the activation key:MCP Response - Multiple Pricing Options
Some signals offer multiple pricing models. The buyer selects one and passes itspricing_option_id in report_usage:
MCP Request - Buyer Querying Multiple DSP Platforms
A buyer checking availability across multiple DSP platforms:MCP Response - Buyer With Multi-Platform Access
A buyer with credentials for both The Trade Desk and Amazon DSP receives keys for both platforms:A2A Request
Natural Language Invocation
Explicit Skill Invocation
A2A Response
A2A returns results as artifacts with the same data structure:Protocol Transport
- MCP: Direct tool call with arguments, returns complete response as flat JSON
- A2A: Skill invocation with input, returns structured artifacts with message and data separated
- Data Consistency: Both protocols contain identical AdCP data structures and version information
Scenarios
All Platforms Discovery
Discover all available deployments across platforms:Response
Message: “Found luxury automotive contextual segment from Peer39 with 15% coverage. Live on Index Exchange and OpenX, pending activation on Pubmatic.” Payload:Response Fields
- context_id (string): Context identifier for session persistence
- signals (array): Array of matching signals
- signal_agent_segment_id (string): Universal identifier for the signal
- name (string): Human-readable signal name
- description (string): Detailed signal description
- signal_type (string): Type of signal (marketplace, custom, owned)
- data_provider (string): Provider of the signal data
- coverage_percentage (number): Estimated reach percentage
- deployments (array): Platform-specific deployment information
- platform (string): Target platform name
- account (string, nullable): Specific account if account-specific
- is_live (boolean): Whether signal is currently active
- activation_key (object): The key to use for targeting. Only present when
is_live=trueand the caller has access. See Activation Key Object above. - estimated_activation_duration_minutes (number, optional): Time to activate if not live
- pricing_options (array): Array of pricing options available for this signal. Select one and pass its
pricing_option_idinreport_usage.- pricing_option_id (string): Unique identifier for this pricing option
- model (string): Pricing model —
cpm,percent_of_media, orflat_fee
Error Codes
Discovery Errors
SIGNAL_AGENT_SEGMENT_NOT_FOUND: Signal agent segment ID doesn’t existAGENT_NOT_FOUND: Private signal agent not visible to this principalAGENT_ACCESS_DENIED: Principal not authorized for this signal agent
Discovery Warnings
PRICING_UNAVAILABLE: Pricing data temporarily unavailable for one or more platformsPARTIAL_COVERAGE: Some requested platforms don’t support this signal typeSTALE_DATA: Some signal metadata may be outdated due to provider refresh delays
Usage Notes
- Authentication-Based Keys: Activation keys are only returned when the authenticated caller matches one of the deployment targets
- Permission Security: The signal agent determines key inclusion based on caller identity, not request flags
- Deployment Status: Check
is_liveto determine if activation is needed - Multiple Deployments: Query multiple deployment targets to check availability across platforms
- Activation Required: If
is_liveis false, use theactivate_signaltask - The message field provides a quick summary of the most relevant findings
Iterative refinement
get_signals supports iterative refinement without a separate mode flag. The combination of signal_spec and signal_ids determines the operation:
| Fields provided | Behavior |
|---|---|
signal_spec only | Discovery — find signals matching the description |
signal_ids only | Exact lookup — return specific signals by ID |
signal_ids + signal_spec | Refinement — start from known signals, adjust per the spec |
signal_id values from signals you want to keep, and provide an updated signal_spec describing what to change:
Response - Multiple Signals Found
Response - Partial Success with Warnings
Response - No Signals Found
Implementation Guide
Generating Signal Messages
Themessage field should provide actionable insights: