tickerbot_scan
Every ticker matching a SQL WHERE clause. Right now, or with asof, as of any past date. The q grammar is a flat SQL WHERE over signal names: AND/OR/NOT, comparisons, numeric and string literals, custom signals by name. No JOIN or subqueries. With group_by the result is rollup rows, not tickers. Example: gap_up AND market_cap < 2000000000 AND NOT earnings_this_week.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | SQL WHERE expression. Max 4000 chars; semicolons, comments and write keywords are rejected. Your custom signals are valid here — each expands to its SQL at run time. | |
| dir | No | Sort direction. | desc |
| asof | No | Optional. Target moment as `YYYY-MM-DD` (that day's close) or an ISO timestamp (that intraday moment) — the same read as it stood then, unlimited depth. Full contract under As of a past date. | |
| full | No | Return every signal instead of the default set. Mutually exclusive with `columns` — passing both is a 400. | |
| limit | No | Page size. Max 100. Aggregate mode does not paginate — it sets `truncated: true` when groups were cut, so sort with `order` to keep the ones you want. | |
| order | No | Signal to sort by. In aggregate mode the default is the count alias `tickers` — or, with a custom `select`, the last item's alias — sorted NULLS LAST with the group keys as tiebreak. | change_1d_pct |
| cursor | No | Opaque cursor from the previous response's `next_cursor`. Row mode only. | |
| having | No | Filter the aggregate rows (requires `group_by`). Custom signals are valid here too. | |
| select | No | Aggregate output items (requires `group_by`). Default: the group keys + `COUNT(*) AS tickers`. Supports count/avg/sum/min/max/stddev/string_agg/bool_and/bool_or plus `FILTER (WHERE …)`, and your custom signals inside expressions. Alias with `AS`; a last item without one is a 400. | |
| columns | No | Extra signals per row, ADDITIVE — the defaults are always present (ticker, name, asset_class, asset_type, price, change_1d_pct, gap_pct, relative_volume, market_cap). `fields` accepted as an alias. | |
| group_by | No | AGGREGATE MODE: 1–6 group keys (signals, expressions, or one of your custom signals as a boolean key). Results become rollup rows. Name a key with `AS` to choose its JSON key (`market_cap > 1e11 AS mega`); an un-named expression is named for you rather than returned as `?column?`. Incompatible with `columns`/`full`/`cursor`; works with `asof`. | |
| interval | No | Grain the past state is reconstructed at: `1m`, `1h`, `1d`, or `auto` (default). Only valid alongside `asof` — a live read with `interval` is a 400. Details under As of a past date. | auto |
| universe | No | Slug of a system universe (`top_10`, `top_100`) or one of your own. Omitted, the scan runs across all ~21,072 tracked tickers. | |
| asset_class | No | One or more asset classes — slug or comma-separated list (`stocks`, `rates`, `crypto`, `fx`). Validated for shape, not against a fixed list, so a well-formed class we don't track simply matches nothing. Echoed in `query`. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _meta | No | `null_coverage` reports, per signal in the predicate, how many in-scope rows are NULL and therefore never evaluated — absence from `results` means "no value", not "did not match". `scope` additionally describes an explicit `universe`. | |
| as_of | Yes | Server time this response was assembled (ISO 8601). | |
| count | Yes | Rows in this page. | |
| query | Yes | Your query, echoed — `q`, `order`, `dir`, `limit`, and any scope. | |
| results | Yes | One row per match — every signal on the schema page, plus any you named. | |
| truncated | No | Aggregate mode only (`group_by`): `true` when the rollup stopped at its row cap. Aggregate responses are unpaged, so `next_cursor` is absent there. | |
| next_cursor | No | Opaque token for the next page; `null` on the last page. Pass it back as `cursor`. |