tickerbot.io

Query news

GEThttps://api.tickerbot.io/v2/news

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.

string

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.

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.

string

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.

string

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.

string

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.

number

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.

string

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). 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.

string

Only with group_by. HAVING clause on the rollup (max 1000 chars).

string

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).

stringenumdefault desc

Sort direction.

ascAscending: smallest or earliest first.
descdefaultDescending: largest or most recent first.
integerdefault 50

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.

string

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.

as_ofstring

Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).

queryobject

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.

countnumber

The 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_cursorstring

Opaque token for the next page; null on the last page. Pass it back as cursor with the same params. Rollups do not page.

truncatedboolean

Rollups only (group_by): true when limit cut the group list.

resultsarray

Articles (one per article per mention when you name a per-mention field), or rollups when you passed group_by.

idnumber

The article's id. Stable; use it to drop duplicates.

time_publishedstring

When the article was published (ISO 8601).

titlestring

Headline.

summarystringoptional

The publisher's summary. Not in the default row: name it in select.

sourcestring

Publisher name.

source_domainstringoptional

Publisher's domain.

categorystringoptional

The feed's category for the source.

authorsarrayoptional

Bylines.

topicsarrayoptional

Topics the article is tagged with, each topic and relevance_score.

overall_sentiment_scorenumberoptional

The article's overall sentiment, -1 to 1.

overall_sentiment_labelstringenumoptional

The article's overall sentiment label, from overall_sentiment_score.

BearishScore from -1 to -0.35.
Somewhat-BearishScore from -0.35 to -0.15.
NeutralScore from -0.15 to 0.15.
Somewhat-BullishScore from 0.15 to 0.35.
BullishScore from 0.35 to 1.
tickersarray

Every ticker the article mentions.

mentionsarray

How the article treats each ticker it mentions, in the order of tickers.

tickerstring

The ticker mentioned.

sentiment_scorenumberoptional

The article's sentiment toward this ticker, -1 to 1. null on articles that carry a label only.

sentimentstringenumoptional

The sentiment label for this ticker, from sentiment_score.

BearishScore from -1 to -0.35.
Somewhat-BearishScore from -0.35 to -0.15.
NeutralScore from -0.15 to 0.15.
Somewhat-BullishScore from 0.15 to 0.35.
BullishScore from 0.35 to 1.
relevancenumberoptional

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.

banner_imagestringoptional

Image URL, when the publisher gives one.

urlstring

Link to the article.

created_atstringoptional

When 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.

tickerstringoptional

Per-mention rows only: the ticker this row is about.

sentiment_scorenumberoptional

Per-mention rows only. The article's sentiment toward this ticker, -1 to 1. null on articles that carry a label only.

sentimentstringenumoptional

Per-mention rows only. The sentiment label for this ticker, from sentiment_score.

BearishScore from -1 to -0.35.
Somewhat-BearishScore from -0.35 to -0.15.
NeutralScore from -0.15 to 0.15.
Somewhat-BullishScore from 0.15 to 0.35.
BullishScore from 0.35 to 1.
relevancenumberoptional

Per-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.

CodeMeaning
200Success: the response shape is documented under Returns above.
400bad_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.
  • News is stocks-only: a crypto, FX, metal or rate symbol is a 400 naming its asset class.
  • Both GET and POST are supported; POST takes the same parameters in the body for long queries.
  • Without group_by, each result is one article: by default id, time_published, title, url, source, tickers, overall_sentiment_score, overall_sentiment_label and mentions. Name any article field (Returns lists them) in select to get it.
  • Per-ticker mentions. An article mentions several tickers and treats each one differently. ticker, relevance, sentiment_score and sentiment describe one mention (the same fields as Query events with kind=news). Name any of them in q, select, order or group_by and each result becomes one article per mention, carrying those four fields (with a select, the fields you name plus ticker, always): q=ticker = 'NVDA' AND sentiment_score < -0.3 returns the articles negative about NVDA, and group_by=ticker rolls up per ticker. mentions carries 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.

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"