Discover signals

POST /api/v2/storefront/signals/discover Queries signals agents over AdCP to surface segments matching a natural-language spec or a set of known IDs. Results are not persisted — register a returned signal with Create signal to manage it.

Request

curl -X POST https://api.interchange.io/api/v2/storefront/signals/discover \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "example_signals_agent",
    "signalSpec": "in-market auto intenders, last 30 days",
    "limit": 25
  }'

{
  "agentId": "example_signals_agent",
  "signalIds": ["example_auto_intenders_30d", "example_luxury_auto_30d"]
}

Parameters

Field	Type	Required	Notes
`agentId`	string	No	Restrict the query to one signals agent (max 255)
`signalSpec`	string	No	Natural-language description of the segment to find (max 5000)
`signalIds`	string[]	No	Look up specific signals by ID (max 100)
`limit`	integer	No	Max results, up to 100. Default `20`
`offset`	integer	No	Result offset. Default `0`

Response

{
  "agentResults": [
    {
      "agentId": "example_signals_agent",
      "agentName": "Example Signals",
      "success": true,
      "signalCount": 2
    }
  ],
  "signals": [
    {
      "signalId": "example_auto_intenders_30d",
      "name": "Auto Intenders - 30 Day",
      "description": "Users showing in-market auto shopping behavior in the last 30 days",
      "dataProvider": "Example Data Co",
      "coveragePercentage": 64.2,
      "access": [
        {
          "advertiserId": null,
          "visibility": "PUBLIC",
          "price": {
            "pricing_option_id": "po_cpm_example_auto",
            "pricing_model": "cpm",
            "currency": "USD",
            "fixed_price": 1.75
          }
        }
      ],
      "regions": null,
      "keyType": null,
      "metadata": null
    }
  ],
  "total": 2
}

agentResults reports per-agent success and counts (with an error string on failure); signals is the merged catalog of matches. Discovered signals are not stored until you register them.

Errors

400 VALIDATION_ERROR — signalIds exceeds 100 entries, or limit is out of range.
401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Signal tasks

All signal operations

Create signal

List signals

Browse registered signals

Signal overview

Fields, lifecycle, and concepts

Delete signal Get signal

⌘I

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Parameters

Response

Errors

Signal tasks

Create signal

List signals

Signal overview

​Request

​Parameters

​Response

​Errors

​Related

Signal tasks

Create signal

List signals

Signal overview

Request

Parameters

Response

Errors

Related