# POST /v2/scan/subscribe

**Subscribe to a scan query**

Subscribes to a free-form `q` (same grammar as `GET /v2/scan`). The webhook delivers the match set every time it changes (tickers entering or leaving). Optionally scope to a `universe`. Max `q` length is 1500 chars.

## Plan access

- **Plan access.** Included on every plan.
- **Cadence.** Hobby 5m · Pro 1m · Scale 1m · Enterprise 1m.
- **Capacity.** Unlimited on every paid plan.

## Body parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `q` | body | string | yes | WHERE-clause expression using signal/column names. Max 1500 chars. Example: `gap_up AND small_cap AND high_volume_alert`. |
| `universe` | body | string | no | System or user-owned universe to scope the scan (e.g. `top_100`). |
| `target_url` | body | string | no | https:// URL to POST when the match set changes. Omit for in-app delivery. |
| `cadence` | body | string | no | Allowed: `1m`, `5m`, `15m`, `hourly`, `nyse_open`. Defaults to plan max. Enum: `1m`, `5m`, `15m`, `hourly`, `nyse_open`. |
| `name` | body | string | no | Human-readable label (up to 80 chars). Defaults to `scan: <q>`. |

## Status codes

- **200** — Webhook subscription created.
- **400** — `bad_request` or `invalid_query` — missing/malformed `q`, or invalid `target_url`/`cadence`.
- **403** — `webhook_tier_required`, `webhook_limit_reached`, or `cadence_above_plan_max`.

## Sample response

```json
{
  "id": "wh_eW9rTq-c52v",
  "name": "scan: gap_up AND small_cap AND high_volume_alert",
  "q": "gap_up AND small_cap AND high_volume_alert",
  "cadence": "5m",
  "target_url": "https://example.com/hook",
  "delivery": "webhook",
  "status": "pending_verification",
  "subscription_origin": { "type": "scan", "ref": "q", "condition": null },
  "created_at": 1737580800
}
```

## Examples

### Subscribe to a free-form scan

Request:

```shell
curl -X POST "https://api.tickerbot.io/v2/scan/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"gap_up AND small_cap AND high_volume_alert","target_url":"https://example.com/hook","cadence":"5m"}'
```

Response (`200`):

```json
{
  "id": "wh_eW9rTq-c52v",
  "name": "scan: gap_up AND small_cap AND high_volume_alert",
  "q": "gap_up AND small_cap AND high_volume_alert",
  "cadence": "5m",
  "target_url": "https://example.com/hook",
  "delivery": "webhook",
  "status": "pending_verification",
  "subscription_origin": { "type": "scan", "ref": "q", "condition": null },
  "created_at": 1737580800
}
```

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/scan/subscribe