← tickerbot.io
View as markdown
Endpoints › News

Query news

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

SQL query over the news archive. Article rows, or rollups when you group them.

Query parameters

string

Articles mentioning this symbol (ANDed with q).

string[]

Comma list, up to 50 — articles mentioning ANY of them. Not combinable with ticker or universe.

string

Universe slug — articles mentioning any member. Not combinable with ticker/tickers.

string

Earliest time_published (inclusive) — strict ISO: YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS]Z. (since accepted as an alias.)

string

Articles strictly before this instant — same strict ISO subset, matching /v2/events. (until accepted as an alias.)

string

Full-text search over title + summary — websearch grammar: apple earnings (all words), "price target" (phrase), chips OR semiconductors, -crypto (negation). Max 200 chars. ANDs with q and the scoping params. Language-stemmed English.

string

WHERE clause over the news_article table. Max 4000 chars. Required UNLESS search or a scoping param (ticker/tickers/universe/from/to) is present — the simplest call needs no SQL. Queryable columns: time_published, title, summary, source, source_domain, category, authors, topics, overall_sentiment_score, overall_sentiment_label, tickers, ticker_data, banner_image, url, id, created_at — plus tk, the per-ticker UNNEST alias. Signal/state columns are not joinable here. See the signals catalog for columns + flags you can compose.

string

Sort — a bare column name or SELECT alias only (put expressions in select and order by their alias). Defaults to time_published (article rows) or volume (aggregate rows).

enumdefault desc

Sort direction.

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

Page size. Max 1000.

string

Opaque pagination cursor from a prior response's next_cursor.

string[]

AGGREGATE MODE: comma-separated group keys, 1-6 (max 1000 chars). Switches the response to rollup rows. Use tk to roll up per ticker without writing the UNNEST. Name a key with AS to choose its JSON key; an un-named expression is named for you rather than returned as ?column?.

string[]

Columns/expressions to return (max 2000 chars). Defaults to article columns (no group_by) or <group_by cols>, COUNT(*) AS volume (with group_by).

string

HAVING clause on the aggregate (max 1000 chars). Requires group_by.

Returns

as_ofstring

Server time this response was assembled (ISO 8601).

queryobject

Your filters, echoed.

countnumber

Rows in this page.

next_cursorstring

Opaque token for the next page; `null` on the last page. Pass it back as `cursor`.

truncatedboolean

Aggregate mode only (`group_by`): `true` when the rollup stopped at its row cap.

resultsarray

Article rows, or rollup rows when you passed `group_by`. Aggregate responses add `truncated: true` when `limit` cut the group list.

Status codes

200
Success — the response shape is documented under Returns above.
400
bad_request or invalid_query — missing/malformed q, unknown column, or invalid parameter.

Notes

  • Without group_by, each result is one article: id, time_published, title, source, tickers, overall_sentiment_score, overall_sentiment_label. With group_by set, results become aggregate rollups and the default SELECT becomes <group_by cols>, COUNT(*) AS volume. Use the tk alias — an auto-UNNEST of tickers — to roll up per ticker without writing the join.
  • Same scoping sugar as /v2/events: ticker/tickers/universe and from/to AND into the WHERE clause, and q is optional once any of them is present — ?ticker=NVDA&from=2026-07-01 needs no SQL at all.
  • There is no asof parameter here: "as of" is a WHERE filter on time_published, because every article already carries the moment it was published.
  • Both GET and POST are supported; the POST body takes the same parameter names, for queries too long to fit in a URL.
  • /v2/news is the canonical path — the log-shaped endpoints read uniformly (/v2/scan, /v2/news, /v2/events) — and the original spelling /v2/news/scan answers identically. The anonymous sandbox mirrors both spellings, GET and POST, capped at 50 rows.

More examples

Top tickers by article volume — single day
curl "https://api.tickerbot.io/v2/news?from=2026-08-10&to=2026-08-11&group_by=tk&order=volume&dir=desc&limit=3" \
  -H "Authorization: Bearer YOUR_KEY"
Response
{
  "as_of": "2026-08-11T22:58:32.284Z",
  "query": {
    "q": null,
    "from": "2026-08-10",
    "to": "2026-08-11",
    "select": null,
    "group_by": ["tk"],
    "having": null,
    "order": "volume",
    "dir": "desc",
    "limit": 3
  },
  "count": 3,
  "next_cursor": null,
  "truncated": true,
  "results": [
    { "tk": "AMD", "volume": 43 },
    { "tk": "BAC", "volume": 40 },
    { "tk": "JPM", "volume": 35 }
  ]
}