tickerbot_query_events
Query corporate events—earnings, dividends, splits, filings, insider trades, analyst actions, news and signals—with SQL filters by ticker or time window. Get stable IDs for deduplication.
Instructions
Queries events with SQL across every ticker or a screen's matches: earnings, dividends, splits, filings, insider trades and analyst actions, plus opt-in estimate revisions, news and signal firings. Requires at least one bound: a ticker scope (ticker/universe) or a time window (from/to); q alone is not a bound. With one kind, its payload fields are bare names in q/select/group_by (q: firm ILIKE 'Morgan Stanley', q: relevance >= 0.8 on news); tickerbot_list_event_kinds lists them. join: state adds the ticker's signals as of each event. Every result has a stable id: use it to drop duplicates. kind: signal takes custom signals too.
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_query_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. |