tickerbot_query_news
Query news articles by ticker, keyword, or SQL filters and return per-ticker relevance and sentiment scores, plus grouped rollups for aggregated views.
Instructions
Queries news with SQL for any ticker or a screen's matches: articles with how each one treats every ticker it mentions, or rollups when you group them. ticker (one or a comma list) keeps articles that mention it; add min_relevance: 0.8 to keep only articles about it. Each article carries mentions: per ticker, relevance and sentiment_score/sentiment. Naming ticker, relevance, sentiment_score or sentiment in q/select/group_by gives one row per article per mention: q: ticker = 'NVDA' AND sentiment_score < -0.3 is articles negative about NVDA. search is full-text over title and summary. Rollups with group_by/having return truncated: true instead of paging.
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_news"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | WHERE clause over news articles. Max 4000 chars. Required unless `search`, `ticker`, `universe`, `from` or `to` is present. Takes every article field under Returns except `mentions`, plus the per-mention fields `ticker`, `relevance`, `sentiment_score` and `sentiment` (one article per mention). | |
| to | No | Articles strictly before this instant, in the same strict ISO subset as `from` (as on `/v2/events`). A bare `YYYY-MM-DD` means through the end of that day (the ET calendar day), so `from` and `to` on the same date return that day. | |
| dir | No | Sort direction. Values: asc: Ascending: smallest or earliest first. desc: Descending: largest or most recent first. | desc |
| from | No | Earliest `time_published` (inclusive), in strict ISO: `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM[:SS]Z`. A bare date starts at 00:00 ET that day. | |
| limit | No | Page size (articles) / max groups (a `group_by` rollup). Articles take up to 1000 until 2027-01-12, then 100, and page the rest with `next_cursor`. A rollup does not page: it returns up to `limit` groups, every group up to 1000 by default, and sets `truncated: true` when there are more. A larger value is clamped to the max, not an error; see Deprecations. | |
| order | No | Sort by a bare field name or SELECT alias only (put expressions in `select` and order by their alias). Defaults to `time_published` (articles) or `volume` (rollups; with your own `select` that has no `volume` column, its last column's alias). | |
| cursor | No | From a prior response's `next_cursor`. Send it with the same params as the first page (`limit` may change). It holds the position and pins the read: a page whose params differ from the first page's, or a cursor sent alone, is a 400 naming the param to send. | |
| having | No | Only with `group_by`. HAVING clause on the rollup (max 1000 chars). | |
| search | No | Full-text search over `title` + `summary`, in websearch grammar: `nvidia earnings` (all words), `"price target"` (phrase), `chips OR semiconductors`, `-crypto` (negation). Max 200 chars. ANDs with `q` and the other filters. Language-stemmed English. | |
| select | No | Fields or expressions to return (max 2000 chars). Defaults to the article row (no `group_by`) or `<group_by keys>, COUNT(*) AS volume` (with `group_by`). `*` returns every article field under Returns plus `mentions` (on a per-mention row, the mention's four fields too). `mentions` is selectable on its own. | |
| ticker | No | One ticker or a comma list (up to 50): articles that mention any of them. Not combinable with `universe`. Per-mention rows still list every ticker an article mentions; put `ticker = 'NVDA'` in `q` for one ticker's rows. | |
| group_by | No | Comma-separated group keys, 1-6 (max 1000 chars); the response becomes rollups. `ticker` rolls up per ticker mentioned. Name a key with `AS` to choose its JSON key; an un-named expression is named for you. | |
| 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`. Articles that mention any member. Not combinable with `ticker`. | |
| min_relevance | No | Only with `ticker` or `universe`. Keeps an article only when it is about one of the tickers, meaning that ticker's `relevance` (0 to 1) is at least this value. `0.8` drops passing mentions. Omitted: every article that mentions them. `400` without a ticker scope; in `q`, filter the mention itself: `ticker = 'NVDA' AND relevance >= 0.8`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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: articles, one row per mention on a per-mention read, or groups on a rollup. | |
| query | Yes | Your request echoed, each param with its effective value, in the documented param order. `ticker` is the ticker scope as a list. A param you did not send is `null`. | |
| results | Yes | Articles (one per article per mention when you name a per-mention field), or rollups when you passed `group_by`. | |
| not_found | No | With `ticker` or `universe`: what you named that does not exist: the symbols we do not track, in request order, or an unknown `universe` id; an empty array when every one was found. A typo here is listed, not read as "no news". | |
| truncated | No | Rollups only (`group_by`): `true` when `limit` cut the group list. | |
| _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 | Yes | Opaque token for the next page; `null` on the last page. Pass it back as `cursor` with the same params. Rollups do not page. |