# GET /v2/analyst/events

**List analyst events**

Filter-based reader over the analyst_events archive (per-event analyst actions back to 2012). The same feed powers the `recent_*` analyst flags on /v2/scan and the consensus snapshot columns on the ticker object — this endpoint gives you the underlying discrete events.

All filter params are AND-combined, and at least one of `ticker`, `tickers`, `since`, `until`, `firm`, or `action` is required (an unfiltered full-history scan is rejected with 400). Rows come back newest-first (timestamp DESC, then event_id ASC); page older with the `cursor` from a prior response. When a cursor is supplied, every filter except `limit` is ignored.

## Plan access

- **Plan access.** Available on every plan, alongside the live `last_rating_date` / `last_rating_firm` / `last_rating_action` columns on the ticker object and the `recent_*` analyst flags on /v2/scan.
- **Rate limit.** Hobby 600/min · Pro 6,000/min · Scale 60,000/min.
- **Per-call cap.** Scale/Enterprise: 1000 rows. History back to 2012.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `ticker` | query | string | no | Single-ticker filter. Takes precedence over `tickers`. Example: `AAPL`. |
| `tickers` | query | string | no | Comma-separated ticker filter. Max 50 symbols. Example: `AAPL,NVDA,MSFT`. |
| `since` | query | string | no | Events at or after this instant. ISO date or datetime. Example: `2024-01-01`. |
| `until` | query | string | no | Events strictly before this instant. ISO date or datetime. Example: `2024-12-31`. |
| `firm` | query | string | no | Case-insensitive analyst-firm match. Example: `Morgan Stanley`. |
| `action` | query | string | no | Exact rating-action filter. Enum: `upgrades`, `downgrades`, `initiates_coverage_on`, `maintains`, `reiterates`, `assumes`, `reinstates`, `suspends`. |
| `limit` | query | integer | no | Page size. Max 1000 on Scale/Enterprise. Default: `50`. |
| `cursor` | query | string | no | Opaque pagination cursor from a prior response's `next_cursor`. Ignores all filters except `limit`. |

## Status codes

- **200** — Envelope with `as_of`, `query`, `count`, `next_cursor`, and `results`.
- **400** — `bad_request` — no filter supplied, too many tickers (>50), invalid `since`/`until`, or unknown `action`.

## Sample response

```json
{
  "as_of": "2026-06-29T13:02:11.000Z",
  "query": {
    "ticker": "AAPL",
    "tickers": null,
    "since": null,
    "until": null,
    "firm": null,
    "action": null,
    "limit": 3
  },
  "count": 3,
  "next_cursor": "eyJhZnRlcl90aW1lc3RhbXAiOiIyMDI2LTA2LTEwVDEyOjAwOjAwLjAwMFoiLCJhZnRlcl9ldmVudF9pZCI6OTkxMjN9",
  "results": [
    {
      "event_id": 99201,
      "ticker": "AAPL",
      "timestamp": "2026-06-24T11:30:00.000Z",
      "firm": "Morgan Stanley",
      "analyst": "Erik Woodring",
      "action": "maintains",
      "rating": "Overweight",
      "previous_rating": "Overweight",
      "price_target": 235,
      "previous_price_target": 220,
      "price_target_action": "raises",
      "importance": 3
    }
  ]
}
```

## Examples

### Recent rating actions on one ticker

Request:

```shell
curl "https://api.tickerbot.io/v2/analyst/events?ticker=AAPL&limit=3" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
{
  "as_of": "2026-06-29T13:02:11.000Z",
  "query": {
    "ticker": "AAPL",
    "tickers": null,
    "since": null,
    "until": null,
    "firm": null,
    "action": null,
    "limit": 3
  },
  "count": 3,
  "next_cursor": "eyJhZnRlcl90aW1lc3RhbXAiOiIyMDI2LTA2LTEwVDEyOjAwOjAwLjAwMFoiLCJhZnRlcl9ldmVudF9pZCI6OTkxMjN9",
  "results": [
    {
      "event_id": 99201,
      "ticker": "AAPL",
      "timestamp": "2026-06-24T11:30:00.000Z",
      "firm": "Morgan Stanley",
      "analyst": "Erik Woodring",
      "action": "maintains",
      "rating": "Overweight",
      "previous_rating": "Overweight",
      "price_target": 235,
      "previous_price_target": 220,
      "price_target_action": "raises",
      "importance": 3
    }
  ]
}
```

### Downgrades across a watchlist since a date

Request:

```shell
curl "https://api.tickerbot.io/v2/analyst/events?tickers=NVDA,AMD,INTC&action=downgrades&since=2026-01-01" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
{
  "as_of": "2026-06-29T13:02:11.000Z",
  "query": {
    "ticker": null,
    "tickers": ["NVDA", "AMD", "INTC"],
    "since": "2026-01-01T00:00:00.000Z",
    "until": null,
    "firm": null,
    "action": "downgrades",
    "limit": 50
  },
  "count": 1,
  "next_cursor": null,
  "results": [
    {
      "event_id": 98044,
      "ticker": "INTC",
      "timestamp": "2026-03-12T09:15:00.000Z",
      "firm": "Goldman Sachs",
      "analyst": "Toshiya Hari",
      "action": "downgrades",
      "rating": "Sell",
      "previous_rating": "Neutral",
      "price_target": 18,
      "previous_price_target": 22,
      "price_target_action": "lowers",
      "importance": 4
    }
  ]
}
```

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/analyst/events