Skip to main content
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
  }'

​
Parameters

FieldTypeRequiredNotes
agentIdstringNoRestrict the query to one signals agent (max 255)
signalSpecstringNoNatural-language description of the segment to find (max 5000)
signalIdsstring[]NoLook up specific signals by ID (max 100)
limitintegerNoMax results, up to 100. Default 20
offsetintegerNoResult 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": [
        {
          "seatId": 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

Register a discovered signal

List signals

Browse registered signals

Signal overview

Fields, lifecycle, and concepts