> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Discover signals

> Query signals agents via AdCP to find available segments

`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](/v2/storefront/signals/tasks/create-signal) to manage it.

## Request

<CodeGroup>
  ```bash curl theme={null}
  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
    }'
  ```

  ```json By known signal IDs theme={null}
  {
    "agentId": "example_signals_agent",
    "signalIds": ["example_auto_intenders_30d", "example_luxury_auto_30d"]
  }
  ```
</CodeGroup>

## 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

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Signal tasks" href="/v2/storefront/signals/tasks" icon="list-check">
    All signal operations
  </Card>

  <Card title="Create signal" href="/v2/storefront/signals/tasks/create-signal" icon="plus">
    Register a discovered signal
  </Card>

  <Card title="List signals" href="/v2/storefront/signals/tasks/list-signals" icon="list">
    Browse registered signals
  </Card>

  <Card title="Signal overview" href="/v2/object-guides/signal" icon="wave-pulse">
    Fields, lifecycle, and concepts
  </Card>
</CardGroup>