# GET /v2/news

**Query news archive**

One endpoint, two shapes. Without `group_by`, each result is one article (default columns: `id`, `time_published`, `title`, `source`, `tickers`, `overall_sentiment_score`, `overall_sentiment_label`). With `group_by` set, results are aggregate rollups — default SELECT becomes `<group_by cols>, COUNT(*) AS volume`. Use the `tk` alias (auto-UNNEST of `tickers`) to roll up per ticker without writing the join.

"As-of" is just a WHERE filter on `time_published` — there is no dedicated asof parameter.

Both `GET` and `POST` are supported; `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`); the original spelling `/v2/news/scan` answers identically, forever.

## Plan access

- **Plan access.** Available on every plan, alongside the live `news_volume` and `news_volume_weighted_sentiment` columns on the ticker object.
- **Rate limit.** Free 60/min · Hobby 600/min · Pro 6,000/min · Scale 60,000/min.
- **Per-call cap.** 1000 rows per call on every plan. History back to 2015.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `q` | query | string | yes | WHERE clause over the news_article table. Max 4000 chars. Example: `time_published >= NOW() - INTERVAL '7 days' AND 'NVDA' = ANY(tickers)`. |
| `select` | query | string | no | Comma-separated columns/expressions to return. Defaults to article columns (no `group_by`) or `<group_by cols>, COUNT(*) AS volume` (with `group_by`). |
| `group_by` | query | string | no | Comma-separated group keys. Switches the response to aggregate rows. Use `tk` to roll up per ticker. |
| `having` | query | string | no | HAVING clause on the aggregate. Requires `group_by`. |
| `order` | query | string | no | Sort column or alias. Defaults to `time_published` (article rows) or `volume` (aggregate rows). |
| `dir` | query | string | no | Sort direction. Enum: `asc`, `desc`. Default: `desc`. |
| `limit` | query | integer | no | Page size. Max 1000 (every plan — news is ungated). Default: `50`. |
| `cursor` | query | string | no | Opaque pagination cursor from a prior response's `next_cursor`. |

## Status codes

- **200** — Envelope with `as_of`, `query`, `count`, `next_cursor`, and `results`.
- **400** — `bad_request` or `invalid_query` — missing/malformed `q`, unknown column, or invalid parameter.

## Sample response

```json
{
  "as_of": "2026-05-14T11:41:01.000Z",
  "query": {
    "q": "time_published >= NOW() - INTERVAL '7 days' AND 'NVDA' = ANY(tickers) AND overall_sentiment_score < -0.2",
    "select": null,
    "group_by": null,
    "order": "time_published",
    "dir": "desc",
    "limit": 50
  },
  "count": 12,
  "next_cursor": null,
  "results": [
    {
      "id": 9821,
      "time_published": "2026-05-13T18:22:00.000Z",
      "title": "NVDA Slips on Margin Worries",
      "source": "Bloomberg",
      "tickers": ["NVDA"],
      "overall_sentiment_score": -0.34,
      "overall_sentiment_label": "Somewhat-Bearish"
    }
  ]
}
```

## Examples

### Recent bearish NVDA articles

Request:

```shell
curl "https://api.tickerbot.io/v2/news?q=time_published%20%3E%3D%20NOW()%20-%20INTERVAL%20%277%20days%27%20AND%20%27NVDA%27%20%3D%20ANY(tickers)%20AND%20overall_sentiment_score%20%3C%20-0.2" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
{
  "as_of": "2026-05-14T11:41:01.000Z",
  "query": {
    "q": "time_published >= NOW() - INTERVAL '7 days' AND 'NVDA' = ANY(tickers) AND overall_sentiment_score < -0.2",
    "select": null,
    "group_by": null,
    "order": "time_published",
    "dir": "desc",
    "limit": 50
  },
  "count": 12,
  "next_cursor": null,
  "results": [
    {
      "id": 9821,
      "time_published": "2026-05-13T18:22:00.000Z",
      "title": "NVDA Slips on Margin Worries",
      "source": "Bloomberg",
      "tickers": ["NVDA"],
      "overall_sentiment_score": -0.34,
      "overall_sentiment_label": "Somewhat-Bearish"
    }
  ]
}
```

### Top tickers by article volume — single day

Request:

```shell
curl "https://api.tickerbot.io/v2/news?q=time_published%20%3E%3D%20%272026-01-27%27%20AND%20time_published%20%3C%20%272026-01-28%27&group_by=tk&order=volume&dir=desc&limit=20" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
{
  "as_of": "2026-05-14T11:41:01.000Z",
  "query": {
    "q": "time_published >= '2026-01-27' AND time_published < '2026-01-28'",
    "select": null,
    "group_by": ["tk"],
    "order": "volume",
    "dir": "desc",
    "limit": 20
  },
  "count": 20,
  "next_cursor": null,
  "results": [
    { "tk": "NVDA", "volume": 84 },
    { "tk": "AAPL", "volume": 72 },
    { "tk": "TSLA", "volume": 61 }
  ]
}
```

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/news/query