tickerbot_get_signal
Retrieve a signal's catalog definition and screen US stocks or crypto tickers that match it live or as of a past date, using conditions to filter matches.
Instructions
Returns what one signal is (its catalog entry, the same object List signals returns for it) and every ticker matching it, live or on any past date with asof: a screen on that one signal. Returns catalog (what the signal is) every time. Booleans list their matches with no condition; every other type lists them only with one, typed like the signal: ">70" (numeric), "<YYYY-MM-DDTHH:MM:SSZ" (timestamp), ">=YYYY-MM-DD" (date), "=ETF" (string); without it you get the catalog entry and a note. Without order, a non-boolean sorts by its value in the direction the condition implies (< ascending, > descending). To know when each ticker started matching, use tickerbot_query_events with kind=signal, signal=, transition=enter.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"signal": "<signal>"
},
"name": "tickerbot_get_signal"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Sort direction. Omitted: the direction the default order implies, else `desc`. Values: asc: Ascending: smallest or earliest first. desc: Descending: largest or most recent first. | |
| asof | No | Target moment as `YYYY-MM-DD` (that day's close) or an ISO timestamp (that intraday moment; daily-only signals then carry the previous session's close, never that day's): the same read as it stood then, unlimited depth. Full contract under As of a past date. | |
| grain | No | Only with `asof`. Grain the past state is read at: `1m`, `1h`, `1d` or `auto` (default). `auto` blends: each signal comes from its freshest grain at or before the instant (minute, then hourly, then the last closed daily session), so nothing is refused for grain and no ticker is dropped; `_meta.blended` and `_meta.grains_present` say what contributed. Pin a grain for the fastest response: one grain is read instead of three, and every ticker is captured on the same clock. A signal the pinned grain does not store is a `400 interval_unavailable` naming the grains that carry it (`rsi_14`, fundamentals and valuation ratios are `1d`-only). `1m` and `1h` need a timestamp `asof`; with a bare date they are a `400 interval_unavailable`. Values: 1m: Minute. The one-minute state at or before the instant. Covers the most liquid tickers and the signals stored at one minute. Needs a timestamp `asof`; with a bare date it is a `400 interval_unavailable`. 1h: Hour. The hourly state at or before the instant. Covers every ticker and the signals stored hourly. Needs a timestamp `asof`; with a bare date it is a `400 interval_unavailable`. 1d: Day. The last daily session closed before the instant; a bare date reads that day’s close. Covers every ticker and the most signals, including the daily-only ones such as `rsi_14`, fundamentals and valuation ratios. auto: Auto. Each signal from its freshest grain at or before the instant: minute, then hourly, then the last closed daily session. `_meta.blended` and `_meta.grains_present` say what contributed. | auto |
| limit | No | Page size. Max 200 until 2027-01-12, then 100 (a larger value is clamped to the max, not an error; `next_cursor` pages the rest; see Deprecations). | |
| order | No | Signal to sort by (or `ticker`). Omitted: a yes/no signal lists tickers A→Z; any other signal sorts by its value in the direction the condition implies (`<`/`<=` ascending, `>`/`>=` descending). | |
| cursor | No | The previous response's `next_cursor`. Send it with the same params as the first page (`limit` may change); a page whose params differ is a 400 naming the param. | |
| select | No | Signals each match carries beside `value`, e.g. `market_cap,sector`. `*` is every signal: the whole live row, or on an as-of read every signal the read's grain stores. An unknown signal is a 400, beside `*` too. | |
| signal | Yes | A signal name. Booleans (e.g. `golden_cross`, `above_sma_50`) are detected automatically; every other type (numeric `rsi_14`, timestamp `price_asof`, date `earnings_date`, string `asset_class`) requires a `condition`. An object or list signal (`leadership`, `etf_holders`) has no `condition` form: the read returns its catalog entry and a `note`; screen on it with `POST /v2/scan`. | |
| 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`. | |
| condition | No | Lists the matches of a non-boolean signal; without it the response carries the catalog entry and a `note` instead of `results`. The shape follows the signal's `type` in the catalog. Single bound, `<op><value>`. numeric: `>70`, `<=200`, `!=0` (operators `>`, `>=`, `=`, `!=`, `<`, `<=`). timestamp: an ISO instant, `<YYYY-MM-DDTHH:MM:SSZ` or `>=YYYY-MM-DD` (a bare date is midnight UTC). date: `>=YYYY-MM-DD` or `=YYYY-MM-DD`. string: `=ETF` or `!=ETF` (`=` and `!=` only; quotes optional). A relative window ("older than 15 minutes") is a `/v2/scan` query: `price_asof < now() - interval '15 minutes'`. Sending a condition with a boolean or custom signal returns 400 (it does not apply). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Only on a non-boolean signal read without `condition`: says how to list its matches, or, for an object or list signal, to screen on it with `POST /v2/scan`. `count`, `next_cursor` and `results` are absent then. | |
| _meta | No | This endpoint's own keys: `null_coverage` (how many in-scope tickers are `null` on the signal and so never match) and, with `asof`, `grain_scope` and `minute_only_signals_fell_back_to_daily`. 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 | No | The tickers in `results` on this page. | |
| query | Yes | Your request echoed, each param with its effective value: `signal`, `condition`, `universe`, `asof`, `grain`, `select`, `order`, `dir`, `limit`. | |
| signal | Yes | The signal you asked for. | |
| catalog | Yes | The signal's catalog entry: the same object List signals returns for it (description, type, unit, refresh, grains). `null` only when the catalog could not be read; the matches are served regardless. | |
| results | No | Matching tickers: `ticker`, `name`, the signal `value` and any `select` signals. | |
| not_found | No | With `universe` only: the `universe` id you named when it does not exist (the read then has no results); an empty array or absent otherwise. | |
| _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. Pass it back as `cursor`. |