> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals Quick Reference

> Compact reference for executing AdCP Signals Protocol tasks. Use this when interacting with signal agents via call_adcp_agent.

Use the `call_adcp_agent` tool to execute these tasks against any AdCP signal agent.

## Task Overview

| Task              | Purpose                                 | Response Time |
| ----------------- | --------------------------------------- | ------------- |
| `get_signals`     | Discover signals using natural language | \~60s         |
| `activate_signal` | Activate a signal on a platform/agent   | Minutes-Hours |

## Typical Workflow

1. **Discover signals**: `get_signals` with a natural language description of targeting needs
2. **Review options**: Evaluate signals by coverage, pricing, and deployment status
3. **Activate if needed**: `activate_signal` for signals not yet live on your platform
4. **Use in campaigns**: Reference the activation key in your media buy targeting

***

## Task Reference

### get\_signals

Discover signals based on natural language description, with deployment status across platforms.

```json theme={null}
{
  "signal_spec": "High-income households interested in luxury goods",
  "deliver_to": {
    "deployments": [
      {
        "type": "platform",
        "platform": "the-trade-desk",
        "account": "agency-123"
      }
    ],
    "countries": ["US"]
  },
  "filters": {
    "max_cpm": 5.0,
    "catalog_types": ["marketplace"]
  },
  "max_results": 5
}
```

**Key fields:**

* `signal_spec` (string, required): Natural language description of desired signals
* `deliver_to` (object, required): Where signals will be used
  * `deployments` (array): Target platforms/agents with `type`, `platform`/`agent_url`, and optional `account`
  * `countries` (array): ISO country codes where signals will be used
* `filters` (object, optional): Filter by `catalog_types`, `data_providers`, `max_cpm`, `min_coverage_percentage`
* `max_results` (number, optional): Limit number of results

**Deployment types:**

```json theme={null}
// DSP platform
{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123" }

// Sales agent
{ "type": "agent", "agent_url": "https://salesagent.example.com" }
```

**Response contains:**

* `signals`: Array of matching signals with:
  * `signal_agent_segment_id`: Use this in `activate_signal`
  * `name`, `description`: Human-readable signal info
  * `data_provider`: Source of the signal data
  * `coverage_percentage`: Reach relative to agent's population
  * `deployments`: Status per platform with `is_live`, `activation_key`, `estimated_activation_duration_minutes`
  * `pricing`: CPM and currency

***

### activate\_signal

Activate a signal for use on a specific platform or agent.

```json theme={null}
{
  "signal_agent_segment_id": "luxury_auto_intenders",
  "deployments": [
    {
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123-ttd"
    }
  ]
}
```

**Key fields:**

* `signal_agent_segment_id` (string, required): From `get_signals` response
* `deployments` (array, required): Target deployment(s) with `type`, `platform`/`agent_url`, and optional `account`

**Response contains:**

* `deployments`: Array with activation results per target
  * `activation_key`: The key to use for targeting (segment ID or key-value pair)
  * `deployed_at`: ISO timestamp when activation completed
  * `estimated_activation_duration_minutes`: Time remaining if async
* `errors`: Any warnings or errors encountered

***

## Key Concepts

### Deployment Targets

Signals can be activated on two types of targets:

**DSP Platforms:**

```json theme={null}
{
  "type": "platform",
  "platform": "the-trade-desk",
  "account": "agency-123"
}
```

**Sales Agents:**

```json theme={null}
{
  "type": "agent",
  "agent_url": "https://wonderstruck.salesagents.com"
}
```

### Activation Keys

When signals are live, the response includes an activation key for targeting:

**Segment ID format (typical for DSPs):**

```json theme={null}
{
  "type": "segment_id",
  "segment_id": "ttd_segment_12345"
}
```

**Key-Value format (typical for sales agents):**

```json theme={null}
{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}
```

### Signal Types

* **marketplace**: Licensed from data providers (CPM pricing)
* **custom**: Built for specific principal accounts
* **owned**: Private signals from your own data (no cost)

### Coverage Percentage

Indicates signal reach relative to the agent's population:

* 99%: Very broad signal (matches most identifiers)
* 50%: Medium signal
* 1%: Very niche signal

### Asynchronous Operations

Signal activation may take time. Check the response:

* `is_live: true` + `activation_key`: Ready to use immediately
* `is_live: false` + `estimated_activation_duration_minutes`: Activation in progress

Poll or use webhooks to check completion status.

***

## Error Handling

Common error codes:

* `SIGNAL_AGENT_SEGMENT_NOT_FOUND`: Invalid signal\_agent\_segment\_id
* `ACTIVATION_FAILED`: Could not activate signal
* `ALREADY_ACTIVATED`: Signal already active on target
* `DEPLOYMENT_UNAUTHORIZED`: Not authorized for platform/account
* `AGENT_NOT_FOUND`: Private agent not visible to this principal
* `AGENT_ACCESS_DENIED`: Not authorized for this signal agent

Error responses include:

```json theme={null}
{
  "errors": [
    {
      "code": "DEPLOYMENT_UNAUTHORIZED",
      "message": "Account not authorized for this data provider",
      "field": "deployment.account",
      "suggestion": "Contact your account manager to enable access"
    }
  ]
}
```