Subscribe to a scan query

POSThttps://api.tickerbot.io/v2/scan/subscribe

Push a whole query: we POST your endpoint every time the match set changes.

Body parameters

qstringrequired

WHERE-clause expression using signal names — the same grammar and the same 4000-char cap as POST /v2/scan, so anything scannable is subscribable. Custom signals are expanded and frozen in at creation. See the signals catalog for columns + flags you can compose.

universestring

System or user-owned universe to scope the scan. universe_id accepted as an alias. Unknown universes are a 404 universe_not_found.

target_urlstring

https:// URL to POST when the match set changes. Omit for in-app delivery.

channelenum

Delivery channel. webhook (POST to target_url), discord (embed to discord_url), in_app (dashboard only), or mobile_push (requires a device_id from POST /v2/devices/register). Inferred when omitted: webhook if target_url is set, discord if discord_url is set, else in_app. slack is reserved and returns 501.

`webhook`	POST the payload to an HTTPS endpoint you own, signed with `X-Tickerbot-Signature`.
`discord`	Post to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed — the URL is itself the credential.
`in_app`	Deliver to the in-app feed. No external receiver, so nothing to validate and no `test_url`.
`mobile_push`	Push to a registered device. Requires a `device_id` from Register a device.

discord_urlstring

Discord incoming-webhook URL. Required when channel is discord. Stored as a posting credential: the create response echoes it back under channel_config, but every later read (list, get, deliveries) strips it and sets channel_config_present: true instead.

device_idstring

Device to notify, from POST /v2/devices/register. Required when channel is mobile_push; unknown ids are a 404 device_not_found.

cadenceenum

realtime (the default) is evaluated on every data refresh (~1×/min); hourly and nyse_open throttle to a batch schedule. 1m is a deprecated alias for realtime.

`realtime`	Evaluate on every refresh — the canonical value. (`1m` is a deprecated alias that collapses to this.)
`hourly`	Batch schedule: evaluate once an hour.
`nyse_open`	Batch schedule: evaluate once per session, at the NYSE open.

namestring

Human-readable label (up to 80 chars). Defaults to scan: <q>.

columnsstring[]

Extra signals per fired payload match row, beyond the standard set (ticker, name, asset_type, price, change_1d_pct, market_cap). Each must be a real signal; unknown ones are rejected at creation. fields accepted as an alias — and the RESPONSE reports them under fields, as an array.

orderstringdefault market_cap

Signal the payload's match lists are sorted by before the 100-row cap applies, so a truncated list is the deterministic top 100 rather than an arbitrary sample. Must be a real signal (validated at creation).

direnumdefault desc

Sort direction for order.

`asc`	Ascending — smallest or earliest first.
`desc`default	Descending — largest or most recent first.

Headers

Idempotency-Keystring

Optional unique string (≤255 chars). A retry carrying the same key within 24h replays the original response (Idempotency-Replayed: true header) instead of creating a duplicate; a concurrent duplicate gets 409 idempotency_in_flight; reusing a key for a *different* request (another method or path) gets 422 idempotency_key_reused. 5xx responses are not stored — those retries re-execute.

Returns

as_ofstring

Server time this response was assembled (ISO 8601).

idstring

The webhook id — `wh_…`, the handle for every other call on this record.

namestring

Your label for the subscription.

qstring

The stored predicate. Custom signals appear expanded: the SQL is frozen at creation.

rule_idstring

Legacy link to a v1 alert rule; `null` on everything created through v2.

fieldsstring

Extra signals carried on each fired match row; `null` means the standard set.

orderstring

Sort signal for the payload row list; `null` means the evaluator default (`market_cap`).

dirstring

Sort direction for that list; `null` means the default (`desc`).

universe_idstring

Universe the trigger is scoped to, or `null` for the whole market.

cadencestring

How often the trigger is evaluated — `realtime`, `hourly`, or `nyse_open`.

channelstring

Where deliveries go: `webhook`, `discord`, `in_app`, or `mobile_push`.

target_urlstring

Your HTTPS endpoint; `null` on every channel except `webhook`.

deliverystring

Legacy alias of `channel`, kept aligned for older readers.

statusstring

`active` or `disabled`. Auto-disable follows repeated delivery failure.

sourcestring

Which API version created the record; `v2` for anything you create today.

subscription_originobject

Which door created it — `type` (`ticker`/`signal`/`scan`/`event`), its `ref`, and the `condition` in display form.

last_predicate_valuestring

The trigger's value at the last evaluation; `null` until it has run.

created_atnumber

Creation timestamp.

updated_atnumber

Last modification timestamp.

last_firednumber

When a delivery last went out; `null` if it never has.

last_match_setarray

Tickers matching at the last evaluation — the set the next run is diffed against, which is what makes firing edge-triggered.

last_eval_error_atnumber

When the last evaluation error happened; `null` on a healthy hook.

last_errorstring

The last evaluation error; `null` on a healthy hook. The answer to "why is my webhook not firing?".

next_eval_atnumber

When the evaluator will next consider this subscription.

last_evaluated_atnumber

When it was last evaluated; `null` until the first run.

event_kindsarray

Event-trigger webhooks only: the kinds subscribed (`split`, `dividend`, `insider`, `analyst`, `earnings`).

event_qstring

Event-trigger webhooks only: the payload filter, or `null`.

event_tickersarray

Event-trigger webhooks only: the symbols the trigger is scoped to, or `null` for the universe / whole market.

trigger_kindstring

Event-trigger webhooks only: `event`.

channel_configobject

Returned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id).

signing_secretstring

Returned on create only — shown once, never again. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries.

test_urlstring

Returned on create only: the `POST /v2/webhooks/{id}/test` URL for this record.

_metaobject

Returned on create only, and only when the rule or `columns` named a column under its pre-2026-09-07 spelling: `deprecated_columns` lists each one (`requested`, `use`, `note`). The stored rule carries the current name.

Status codes

201

Webhook subscription created — the same shape as GET /v2/webhooks/{id}, plus test_url (wire-delivered channels only) and, uniquely on create, signing_secret (shown once, for HMAC verification) and the raw channel_config you supplied. Later reads strip both.

400

bad_request or invalid_query — missing/malformed q, or invalid target_url/cadence.

403

webhook_tier_required or webhook_limit_reached.

404

universe_not_found — unknown universe; device_not_found — unknown device_id.

409

idempotency_in_flight — a concurrent request carried the same Idempotency-Key.

422

idempotency_key_reused — the Idempotency-Key was already used for a different request.

501

channel_not_implemented — channel: "slack" is reserved.

Notes

Shorthand for POST /v2/webhooks with a { type: "scan" } trigger — one of the four doors to the same webhook object, listed, updated, and deleted at /v2/webhooks. Optionally scope it to a universe.
Subscribes to a free-form q, the same grammar as POST /v2/scan, and fires whenever tickers enter or leave the match set. q takes the same 4,000 characters scan does, checked before custom-signal inlining — so any q the scan endpoint accepts is subscribable.
Payload row lists (matches, current_matches) are capped at 100 entries, while matched_count / current_match_count always carry the true totals and a matches_truncated / current_matches_truncated field appears when a list was capped. A capped list is the top 100 by order (default market_cap descending), and the payload echoes the order/dir used — so the 100 you receive are deterministic and stable between fires, not an arbitrary sample.
Wire-delivered subscriptions (webhook, discord) come back with a test_url. Subscribing does NOT auto-fire — call it to send a real-shape webhook.fired and validate your receiver. In-app subscriptions have no external receiver and carry no test_url.
Custom signals referenced in q are expanded and frozen into the webhook at creation. Editing the signal later does not change this subscription — re-subscribe to apply.

curl -X POST "https://api.tickerbot.io/v2/scan/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "above_sma_200 AND market_cap > 1e10",
    "universe": "top_100",
    "target_url": "https://example.com/hook",
    "name": "Large caps above the 200DMA",
    "columns": [
      "rsi_14",
      "macd_line"
    ],
    "order": "market_cap",
    "dir": "desc"
  }'

Sample response

{
  "as_of": "2026-07-27T16:44:00.000Z",
  "id": "wh_eW9rTq-c52v",
  "name": "scan: above_sma_200 AND market_cap > 1e10",
  "q": "above_sma_200 AND market_cap > 1e10",
  "rule_id": null,
  "fields": null,
  "order": null,
  "dir": null,
  "universe_id": null,
  "cadence": "realtime",
  "channel": "webhook",
  "target_url": "https://example.com/hook",
  "delivery": "webhook",
  "signing_secret": "whsec_…",
  "status": "active",
  "source": "v2",
  "subscription_origin": { "type": "scan", "ref": "q", "condition": null },
  "test_url": "/v2/webhooks/wh_eW9rTq-c52v/test",
  "created_at": 1785170640,
  "updated_at": 1785170640,
  "...": "(evaluator bookkeeping fields)"
}