SQL
A screen is one SQL WHERE clause. Scan takes it as q and a webhook as its trigger; events and news take the same grammar to filter their own records.
The grammar
One WHERE clause; its identifiers depend on where you send it.
- On scan and webhooks: the
qon Scan and its subscriptions. Identifiers are signals of any type: booleans you name directly, numerics, strings and dates you compare, object signals you test with@>(leadership @> '[{"name":"John Ternus"}]'matches the tickers whose leadership lists that person), plus the qualified context tickers below. - On events: Events and the event webhook's
q. Five identifiers:id,ticker,ts,kindandpayload, with jsonb operators on payload fields (payload->>'firm' = 'Goldman Sachs'); with one kind named, its payload fields by bare name (firm = 'Goldman Sachs'). Withjoin=stateticker signals are legal too, as of each event's timestamp; an event webhook'sqalways takes them, at fire time. - On news: News. Article columns (
time_published,source, sentiment) plus the per-mention fields (ticker,relevance,sentiment_score,sentiment), which give one row per article per mention for per-ticker rollups.
Where it goes
The same clause on every surface that takes one: in the JSON body on scan and webhooks, as a URL-encoded q on events and news.
Scan
curl -X POST "https://api.tickerbot.io/v2/scan" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "above_sma_200 AND market_cap > 1e10"
}'Add asof to run the same screen on any past date (As-of).
Webhook
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 market_cap > 1e9",
"target_url": "https://example.com/hook"
}'The webhook fires when a ticker starts matching. Event webhooks take the events grammar in their q.
Events
curl -G "https://api.tickerbot.io/v2/events" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "kind=analyst" \
--data-urlencode "from=2026-10-06" \
--data-urlencode "q=payload->>'action' = 'downgrades'"News
curl "https://api.tickerbot.io/v2/news?ticker=NVDA&q=overall_sentiment_score%20%3C%20-0.2&limit=5" \
-H "Authorization: Bearer YOUR_KEY"Example screens has more, each combining two or three kinds of data.
Context tickers
Reference another symbol inside a screen.
Writing spy.price > spy.sma_50 pulls SPY's signals into the same screen: no second call, no client-side join, every clause evaluated at the same instant (under asof too).
What can be a qualifier
Any symbol the catalog returns, spelled as it appears there.
| example | what it is |
|---|---|
spy | An ETF (the S&P 500 proxy). Any ETF works the same way (qqq, iwm, xlk, ...). |
nvda | Any equity in the catalog: a bellwether, a peer or a competitor. |
r:sofr | A rate (R: prefix): SOFR, fed funds, Treasury yields and spreads. |
x:btcusd | A crypto or FX pair (X: prefix). |
Rules
- A qualifier that is not in the catalog is a
400 unknown_context_tickernaming it, never a raw SQL error or a silent empty result. - Symbols with a dot or hyphen in them (
BRK.B) cannot be qualifiers: the dot is the separator. Everything else in the catalog can, including prefixed ids (r:sofr,x:btcusd). vixanddxyanswer400 context_ticker_unavailable.- There is no cap on refs per screen beyond the 4,000-character limit on
q; each ref is one indexed lookup evaluated once per screen, whatever the symbol. - Refs inside a custom signal's
exprare not rewritten. Keep custom signals single-ticker and put the context ref inq.
Macro-conditioned setup
curl -X POST "https://api.tickerbot.io/v2/scan" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "rsi_oversold AND spy.price > spy.sma_50"
}'RSI-oversold names, but only when the S&P 500 is holding above its 50-day average.
Sector-relative breakout
curl -X POST "https://api.tickerbot.io/v2/scan" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "at_20d_high AND sector = '"'"'Technology'"'"' AND change_1d_pct > xlk.change_1d_pct"
}'Tech breakouts that are also outpacing the tech sector ETF on the same day.
What's accepted
What works, what we reject and the reads that take something narrower than a WHERE clause.
- Everything you'd expect works:
LIKE/ILIKE,IN,BETWEEN,CASE, computed expressions (price / sma_50 > 1.05), casts to whitelisted types (::numeric,::date,::timestamptz, ...) and jsonb containment on an object signal, with the entries to match written as a JSON list (revenue_by_segment @> '[{"name":"Americas"}]'; a value that is not JSON is a 400). - No subqueries or joins. A clause filters one record at a time: a ticker's signals on /v2/scan, an event on /v2/events, an article on /v2/news. The one sanctioned join is
join=stateon /v2/events (a parameter, not SQL you write). - No statement composition.
UNION/EXCEPT/INTERSECT,WITH,SELECT, any DDL/DML keyword, semicolons and SQL comments (--,/* */) are rejected. - Functions are whitelisted: aggregates (
count,avg,sum,min,max,string_agg, ...) inselect/having, plus scalar helpers (coalesce,round,abs,lower,upper,length,date_trunc,extract,now,cardinalityfor astring[]signal's length (etf_holders),jsonb_array_lengthfor an object list (leadership), ...). Anything else (window functions included:OVER (...),row_number,rank,lag) is a 400 naming the function. - No double-quoted identifiers. Write columns bare (
price, not"price"); single quotes are for string literals. - Custom-signal
expris stricter still: comparisons,AND/OR/NOT,IN,BETWEEN,IS [NOT] NULLand arithmetic; functions limited toabs/coalesce/round/least/greatest. NoLIKE/ILIKE, noCASE, no::casts. An expression that works in a scanqcan still be rejected withcompile_failed.
Three reads take other params instead of q: signal matches take condition, one comparator on the named signal (?condition=>70); History and Bars take structured params (select and grain on History, the bar width in the Bars path, from/to); ticker reads are keyed by symbol.