Query news
https://api.tickerbot.io/ v2/ newsQueries 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.
Query parameters
stringFull-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.
string[]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.
stringScope 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.
stringEarliest 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.
stringArticles 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.
numberOnly 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.
stringWHERE 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). See the signals catalog for columns + flags you can compose.
string[]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.
string[]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.
stringOnly with group_by. HAVING clause on the rollup (max 1000 chars).
stringSort 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).
stringenumdefault descSort direction.
asc | Ascending: smallest or earliest first. |
descdefault | Descending: largest or most recent first. |
integerdefault 50Page 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.
stringFrom 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.
Returns
as_ofstringServer time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).
queryobjectYour 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.
countnumberThe rows in results on this page: articles, one row per mention on a per-mention read, or groups on a rollup.
not_foundstring[]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".
next_cursorstringOpaque token for the next page; null on the last page. Pass it back as cursor with the same params. Rollups do not page.
truncatedbooleanRollups only (group_by): true when limit cut the group list.
resultsarrayArticles (one per article per mention when you name a per-mention field), or rollups when you passed group_by.
idnumberThe article's id. Stable; use it to drop duplicates.
time_publishedstringWhen the article was published (ISO 8601).
titlestringHeadline.
summarystringoptionalThe publisher's summary. Not in the default row: name it in select.
sourcestringPublisher name.
source_domainstringoptionalPublisher's domain.
categorystringoptionalThe feed's category for the source.
authorsarrayoptionalBylines.
topicsarrayoptionalTopics the article is tagged with, each topic and relevance_score.
overall_sentiment_scorenumberoptionalThe article's overall sentiment, -1 to 1.
overall_sentiment_labelstringenumoptionalThe article's overall sentiment label, from overall_sentiment_score.
Bearish | Score from -1 to -0.35. |
Somewhat-Bearish | Score from -0.35 to -0.15. |
Neutral | Score from -0.15 to 0.15. |
Somewhat-Bullish | Score from 0.15 to 0.35. |
Bullish | Score from 0.35 to 1. |
tickersarrayEvery ticker the article mentions.
mentionsarrayHow the article treats each ticker it mentions, in the order of tickers.
tickerstringThe ticker mentioned.
sentiment_scorenumberoptionalThe article's sentiment toward this ticker, -1 to 1. null on articles that carry a label only.
sentimentstringenumoptionalThe sentiment label for this ticker, from sentiment_score.
Bearish | Score from -1 to -0.35. |
Somewhat-Bearish | Score from -0.35 to -0.15. |
Neutral | Score from -0.15 to 0.15. |
Somewhat-Bullish | Score from 0.15 to 0.35. |
Bullish | Score from 0.35 to 1. |
relevancenumberoptionalHow much the article is about this ticker, 0 to 1 (1 = it is the subject). q=relevance >= 0.8 keeps the articles about it.
banner_imagestringoptionalImage URL, when the publisher gives one.
urlstringLink to the article.
created_atstringoptionalWhen the article entered the archive (ISO 8601). A time in the data, so ISO like time_published, not the epoch seconds of a webhook's or universe's own created_at.
tickerstringoptionalPer-mention rows only: the ticker this row is about.
sentiment_scorenumberoptionalPer-mention rows only. The article's sentiment toward this ticker, -1 to 1. null on articles that carry a label only.
sentimentstringenumoptionalPer-mention rows only. The sentiment label for this ticker, from sentiment_score.
Bearish | Score from -1 to -0.35. |
Somewhat-Bearish | Score from -0.35 to -0.15. |
Neutral | Score from -0.15 to 0.15. |
Somewhat-Bullish | Score from 0.15 to 0.35. |
Bullish | Score from 0.35 to 1. |
relevancenumberoptionalPer-mention rows only. How much the article is about this ticker, 0 to 1 (1 = it is the subject). q=relevance >= 0.8 keeps the articles about it.
Status codes
| Code | Meaning |
|---|---|
200 | Success: the response shape is documented under Returns above. |
400 | bad_request or invalid_query: missing/malformed q, an unknown field or invalid parameter, from after to, ticker with universe, more than 50 tickers, mentions used outside select, select=* on a rollup, or a cursor sent without its first page's params (the message names the param). A guessed sentiment parameter (sentiment, min_sentiment, sentiment_score_gte, …) is a 400 naming the q that does it. |
Notes
- News is stocks-only: a crypto, FX, metal or rate symbol is a 400 naming its asset class.
- Both
GETandPOSTare supported;POSTtakes the same parameters in the body for long queries. - Without
group_by, each result is one article: by defaultid,time_published,title,url,source,tickers,overall_sentiment_score,overall_sentiment_labelandmentions. Name any article field (Returns lists them) inselectto get it. - Per-ticker mentions. An article mentions several tickers and treats each one differently.
ticker,relevance,sentiment_scoreandsentimentdescribe one mention (the same fields as Query events withkind=news). Name any of them inq,select,orderorgroup_byand each result becomes one article per mention, carrying those four fields (with aselect, the fields you name plusticker, always):q=ticker = 'NVDA' AND sentiment_score < -0.3returns the articles negative about NVDA, andgroup_by=tickerrolls up per ticker.mentionscarries the same values for every ticker on the article row. - On a busy ticker, bound a per-mention read with
from: NVDA's whole history takes 4 to 9 seconds, a 30-day window under one second. - "As of" is a WHERE filter on
time_published: every article already carries the moment it was published.
More examples
The default article row, with mentions
curl "https://api.tickerbot.io/v2/news?ticker=NVDA,MS&limit=1" \
-H "Authorization: Bearer YOUR_KEY"Most-mentioned tickers on a day, with their average sentiment
curl -G "https://api.tickerbot.io/v2/news" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "from=2026-11-14" --data-urlencode "to=2026-11-14" \
--data-urlencode "select=ticker, COUNT(*) AS volume, AVG(sentiment_score) AS avg_sentiment" \
--data-urlencode "group_by=ticker" \
--data-urlencode "limit=3"