tickerbot_list_events
THE events primitive — one timeline over every event log, cross-ticker: dividends, splits, insider transactions, and analyst actions ("all splits this month", "every analyst action in my universe this week", "AAPL's full corporate history" via ticker), plus two opt-in kinds that join only when named: signal (boolean-flag firings) and news. Rows are { ticker, ts, kind, payload }, newest first. Analyst payloads (history to 2012) carry firm/analyst/action/rating/price_target; filter them with firm=/action= (structured, case-insensitive — a q payload match is case-SENSITIVE) — actions: upgrades, downgrades, initiates_coverage_on, maintains, reiterates, assumes, reinstates, suspends, terminates_coverage_on. Use q for other payload conditions: it speaks the SQL grammar over exactly (ticker, ts, kind, payload jsonb); group_by/select/having roll the stream up (aggregates return truncated: true instead of paginating); join=state attaches the ticker's state as of each event. Requires at least one bound: a ticker scope (ticker/tickers/universe), a time window (from/to), or firm/action — q alone is not a bound.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | SQL WHERE over (ticker, ts, kind, payload jsonb) — ONLY those four identifiers. Payload fields via jsonb operators: payload->>'firm' = 'Goldman Sachs', (payload->>'shares')::numeric > 1e6. On kind=signal this requires `signal` (the firing log is ~175M rows); kind=signal takes no group_by. | |
| to | No | Window end: a bare YYYY-MM-DD means through the END of that day (matching bars/series/spans); a timestamp is exclusive — events strictly before it. `until` accepted as alias. | |
| dir | No | Aggregate-mode sort direction. | |
| firm | No | kind=analyst only. Case-insensitive analyst-firm filter (e.g. "Goldman Sachs" matches "goldman sachs") — prefer this over a q payload match, which is case-sensitive. | |
| from | No | Events at or after this ISO date/datetime (inclusive; a bare YYYY-MM-DD means from the start of that day). `since` accepted as alias. | |
| join | No | join=state attaches each event's ticker STATE as of that event's moment (the replay join) under a `state` key — "downgrades where rsi_14 was already under 40" composes with q. Free on every plan. | |
| kind | No | Comma list of kinds to include. Default is the four corporate kinds: dividend, split, insider, analyst. Two more are opt-in and join only when named: `signal` (boolean-flag firings) and `news`. | |
| limit | No | Page size. Max 1000. | |
| order | No | Aggregate-mode sort column/alias. Default: events. | |
| action | No | kind=analyst only. Exact rating-action filter. | |
| cursor | No | Opaque cursor from a prior response — carries the original filters, pass it alone (long q values must be resent alongside it). | |
| having | No | Post-aggregation filter (requires group_by), e.g. COUNT(*) > 5. | |
| select | No | Aggregate-mode output columns (requires group_by). Default: group keys + COUNT(*) AS events. | |
| signal | No | kind=signal only. One built-in boolean flag (e.g. golden_cross). REQUIRED to use `q` or `join` on kind=signal — naming the signal is what keeps the query on an index; optional otherwise. | |
| ticker | No | Single-ticker filter, e.g. AAPL. | |
| tickers | No | Comma-separated tickers, max 50. Mutually exclusive with `universe`. | |
| group_by | No | Comma list of rollup keys — switches to aggregate rows, e.g. payload->>'firm' AS firm, or kind. `AS` names the JSON key; an un-named payload read is keyed by its payload key (payload->>'firm' -> firm). | |
| interval | No | Grain for join=state replay (finest covering tier by default). | |
| universe | No | Universe slug (top_10, top_100, or a saved one) to scope the stream. Mutually exclusive with `tickers`. | |
| transition | No | kind=signal only. `enter` (false->true) or `exit` (true->false). Always optional — an ordinary filter. |