tickerbot_list_events
Lists stock-market events with SQL-style filters, date windows, tickers, and rollups. Deprecated: use tickerbot_query_events instead.
Instructions
Deprecated: works until 2027-01-12. Same as tickerbot_query_events; call that instead.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "tickerbot_list_events"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | SQL WHERE over `id`, `ticker`, `ts`, `kind` and `payload` (plus the ticker's signals with `join=state`). With one `kind`, its payload fields are typed columns by bare name: `amount > 1`, `firm ILIKE 'Morgan Stanley'`, `relevance >= 0.8` on news (List event kinds lists them); with several kinds, use `payload->>'…'`. Max 4000 chars. ANDs with the other filters. | |
| to | No | Window end, in the same strict ISO subset. A bare `YYYY-MM-DD` means through the end of that day; a timestamp is exclusive (events strictly before it). For news, analyst ratings and estimate revisions the day is the ET calendar day; dated kinds use their own dates. For `signal`, the ticker's home-market day: ET for stocks and ETFs, UTC for crypto, FX and rates. | |
| dir | No | A list: `desc` (default) is newest first, `asc` oldest first, paging forward. With `group_by`: the rollup's sort direction. Values: asc: Ascending: smallest or earliest first. desc: Descending: largest or most recent first. | desc |
| from | No | Events at or after this instant, in strict ISO: `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM[:SS]Z`. A bare `YYYY-MM-DD` means from the start of that day. For news, analyst ratings and estimate revisions the day is the ET calendar day (a story at 21:00 ET on Nov 2 is Nov 2); dated kinds use their own dates. For `signal`, the ticker's home-market day: ET for stocks and ETFs, UTC for crypto, FX and rates. | |
| join | No | Set to `state` to use the ticker's signals in `q`, `select`, `group_by` and `having`, read as of each event's timestamp at the grain `grain` picks. On the daily grain an event on day D reads D-1's row, never D's close. A signal and a payload field with the same name (`price` on insider and signal events, `cik` on filing) resolve to the signal; spell the field `payload->>'price'`. Needs `q`, `group_by` or a ticker signal in `select`. Values: state: Add the ticker’s signals, read as of each event’s timestamp at the grain `grain` picks (default `auto`, which blends hourly and daily per event). | |
| kind | No | Comma list of kinds. Leave it out for earnings, dividend, split, filing, insider and analyst. News, signal and estimate_revision come back only when named. List event kinds lists each kind, its fields and its filters. Values: earnings: Quarterly earnings reports: reported vs estimated EPS and the surprise, timestamped at the report date. Default. No filters of its own. Payload. dividend: Cash-dividend declarations, timestamped at the ex-dividend date. Default. No filters of its own. Payload. split: Stock splits and reverse splits, timestamped at the execution date. Default. No filters of its own. Payload. filing: SEC annual and quarterly reports (10-K, 20-F, 40-F, 10-Q), timestamped at the filing date. Default. No filters of its own. Payload. insider: Officer and director trades, one event per reported Form 4 transaction. Default. No filters of its own. Payload. analyst: Upgrades, downgrades, initiations and price-target changes; lands within the hour, 24/7. Default. Filter it with `q` (`firm ILIKE 'Morgan Stanley'`). Payload. estimate_revision: Moves in consensus EPS estimates. Opt-in: included only when named. No filters of its own. Payload. news: Headlines, one event per article × tagged ticker. Opt-in: included only when named. `q=relevance >= 0.8` keeps the articles about the ticker. Payload. signal: A yes/no signal turning on or off, built-in or custom. Opt-in: included only when named. Filters: `signal`, `transition`, `merge_gap_seconds`. Payload. | |
| grain | No | Only with `kind=signal` or `join=state`. With `kind=signal`, the grain the flips are read at: `1m`, `1h` or `1d`, or `auto` (the default), the coarsest grain the signal is stored at. With `join=state`, the grain the ticker's signals are read at: `auto` (default) blends hourly and the last closed daily session per event; see as of a past date. Values: 1m: Minute. With `kind=signal`, the signal turning on and off in the one-minute state. With `join=state`, signals read from the one-minute state at or before each event. 1h: Hour. With `kind=signal`, the signal turning on and off in the hourly state. With `join=state`, signals read from the hourly state at or before each event. 1d: Day. With `kind=signal`, the signal turning on and off in the daily state. With `join=state`, signals read from the last daily session closed before each event. auto: Auto. With `kind=signal`, each signal at its own grain, the coarsest it is stored at (`above_sma_200` at `1d`). With `join=state`, each signal from its freshest grain at or before the event, hourly or the last closed daily session; `group_by` reads use the daily session. | auto |
| limit | No | Page size for a list (default 50): up to 1000 until 2027-01-12, then 100, and the rest pages with `next_cursor`. A `group_by` rollup returns every group up to `limit` (default and max 1000) and sets `truncated: true` when there are more. A larger value is clamped to the max, not an error; see Deprecations. | |
| order | No | With `group_by`: the rollup sort, a bare column or output name (put expressions in `select` and sort by their alias); a group key's name works too: `group_by=payload->>'firm' AS firm&order=firm`. Default: `events`, or with your own `select`, its last column's alias. A list is sorted by `ts`: `order=ts` is accepted there and changes nothing. | |
| cursor | No | Opaque cursor from the previous response. It carries the filters, `dir` and `select`, so pass it alone. A `q`, `ticker` list or `select` too long to ride in it is kept as a fingerprint instead: send that param again with `cursor`, the same as on the first page (`q_truncated` flags `q`). A missing or different value is a 400 naming the param. Not valid with `group_by`. | |
| having | No | Only with `group_by`. Post-aggregation filter. | |
| select | No | Without `group_by`: what each result carries. `id`, `ticker`, `ts` and `kind` always, then the names you list, each at the top level of the result: `payload`, a payload field of the one kind named (`firm`, or `payload->>'firm'`) and with `join=state` a ticker signal. `*` is every field: the whole `payload`, and with `join=state` every signal the read's grain stores. With `group_by`: the rollup's output columns (default: the group keys + `COUNT(*) AS events`), named with `AS` or for you as on `group_by`. | |
| signal | No | Only with `kind=signal`. One signal or a comma list of up to 5: built-in yes/no signals or your custom signals. Required with `q` or `join=state`. An unknown name filters nothing in and is listed in `not_found` (every name unknown: no signal events). See Signal firings. | |
| ticker | No | One ticker or a comma list (up to 50). Not combinable with `universe`. A crypto, FX or rate symbol (`X:BTCUSD`) takes `kind=signal`; every other kind is equities-only and returns `400` naming the symbol's asset class. | |
| group_by | No | Comma list of rollup keys; it switches the response to rollups. Columns (`kind`, `ticker`), payload fields (`firm`, or the explicit `payload->>'firm'`) and expressions over them all roll up. Name a key with `AS` to choose its JSON key: `payload->>'firm' AS firm`. Un-named keys are named for you: a payload read takes its key (`payload->>'firm'` → `firm`), a function keeps the function's name (`lower(ticker)` → `lower`), and anything else falls back to `group_1`, `group_2`. | |
| universe | No | Scope to a built-in universe (`top_10`, `top_100`) or one of your own, by id. An unknown one answers 200 with no results and its id in `not_found`. Not combinable with `ticker`. | |
| transition | No | Only with `kind=signal`. `enter` (false→true) or `exit` (true→false). Values: enter: Enter. The signal turned on: false to true. exit: Exit. The signal turned off: true to false. | |
| merge_gap_seconds | No | Only with `kind=signal`. Merges an exit and re-entry closer than N seconds into one span. Needs one `signal` and a `ticker` list, and does not combine with `q`, `group_by` or `join=state`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _meta | No | With `join=state` only. `grain`, the grain the joined state was read at (`auto` or the pin), and `state_blended: true` under `auto`. Shared keys: see the `_meta` reference. | |
| as_of | Yes | Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of). | |
| count | Yes | The rows in `results` on this page: events, or groups on a rollup. | |
| query | Yes | Your request with each param's effective value, in the documented param order: `kind` (a comma string; `all` when you left it out, meaning the six default kinds), `ticker` (a list), `universe`, `from` and `to` (ISO 8601), the kind's own filters (`signal`, `transition`, `merge_gap_seconds`), `q`, `join`, `grain`, `select`, `group_by`, `having`, `order` (rollups), `dir` and `limit`. `q`, `select`, `group_by` and `having` come back in your spelling, not the SQL they compile to. A param you did not send is `null`. | |
| results | Yes | One result per event (with `select`: `id`, `ticker`, `ts`, `kind` and the named keys), or rollups plus `truncated: true` when an aggregate exceeds `limit`. | |
| not_found | No | With `ticker`, `universe` or `signal`: what you named that does not exist, in request order: the symbols we do not track, an unknown `universe` id, then unknown `signal` names; an empty array when every one was found. A typo here is listed, not read as "no events". | |
| truncated | No | Aggregate mode only (`group_by`): `true` when the rollup stopped at its result cap. Aggregate responses are unpaged, so `next_cursor` is absent there. | |
| _advisories | No | Present only when the response carried a warning: `deprecated` (since, sunset_on, successor, warning; on a deprecated tool, successor names the tool to call), `rate_limit` (warning, retry_after_seconds, limit, remaining, reset_epoch_s) or `monthly_quota` (warning, limit, remaining, reset_epoch_s). | |
| next_cursor | No | Opaque token for the next page; `null` on the last page. A `kind=signal` page can hold fewer than `limit` results, or none, and still carry a `next_cursor`: the read covers a long window in steps and returns what it has after about 6 s (`q` or `join=state`) or 10 s (filter params only), so keep paging until `next_cursor` is `null`. A page that read nothing retries a shorter stretch; if three pages in a row read nothing that way, the read answers `503` `unavailable` with `Retry-After` instead of another empty page, and the same `cursor` can be retried. | |
| q_truncated | No | Only when an oversized `q` could not ride the cursor: resend `q` with `cursor` on later pages. |