# GET /v2/events?kind=estimate_revision

**Estimate revisions**

Every move in the consensus EPS estimate for a company's fiscal quarter or fiscal year, as a timeline event with the old and new value. Opt in by naming `estimate_revision` in `kind`.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `kind` | query | string | yes | Include `estimate_revision` explicitly — e.g. `kind=estimate_revision` alone, or merged with other kinds (`kind=earnings,estimate_revision`). Example: `estimate_revision`. |
| `ticker` | query | string | no | Single symbol. Beats `tickers` when both are passed. Example: `NVDA`. |
| `tickers` | query | string[] | no | Comma-separated symbols, up to 50. Not combinable with `universe`; `ticker` wins when both are passed. Example: `NVDA,AAPL`. |
| `universe` | query | string | no | System or caller-owned universe slug. Example: `top_100`. |
| `from` | query | string | no | `YYYY-MM-DD` or ISO timestamp (inclusive). `since` is accepted as an alias. Example: `2026-09-17`. |
| `to` | query | string | no | `YYYY-MM-DD` or ISO timestamp — a bare `YYYY-MM-DD` means through the end of that day; timestamps are exclusive. `until` is accepted as an alias. Example: `2026-07-01`. |
| `q` | query | string | no | SQL filter. This kind's payload fields are first-class typed columns here: `old_estimate`, `new_estimate`, `change_pct`, `analyst_count` (numeric), `fiscal_date` (date), `horizon`, `direction` (text) — e.g. `direction = 'down' AND change_pct < -5`. `payload->>'…'` works too. Base columns: `ticker`, `ts`, `kind`, `payload`. Example: `direction = 'down' AND change_pct < -5`. |
| `limit` | query | integer | no | Rows per page. Max 1000. Default: `50`. Example: `5`. |
| `cursor` | query | string | no | Opaque cursor from the previous response. |

## Returns

- `as_of` (string) — Server time this response was assembled (ISO 8601).
- `query` (object) — Your filters, echoed.
- `count` (number) — Rows in this page.
- `next_cursor` (string) — Opaque token for the next page; `null` on the last page. Pass it back as `cursor`.
- `results` (array) — One row per revision, newest first.
  - `ticker` (string) — The company whose estimate moved.
  - `ts` (string) — When the new consensus was observed (our nightly estimates refresh), not when an individual analyst filed.
  - `kind` (string) — Always `estimate_revision` on this view.
  - `payload` (object) — The move.
    - `fiscal_date` (string) — End of the fiscal period the estimate is for (`YYYY-MM-DD`).
    - `horizon` (string) — `fiscal quarter` or `fiscal year`.
    - `old_estimate` (number) — Consensus EPS before the move.
    - `new_estimate` (number) — Consensus EPS after the move.
    - `change_pct` (number) — Change in percent of the old value's magnitude (`2.5` = 2.5%).
    - `direction` (string) — `up` or `down`.
    - `analyst_count` (number, optional) — Analysts in the consensus, when the vendor reports it.

## Sample response

```json
{
  "as_of": "2026-09-29T18:20:11.000Z",
  "query": { "kind": "estimate_revision", "universe": "top_100", "since": "2026-09-01T00:00:00.000Z", "limit": 50 },
  "count": 1,
  "next_cursor": null,
  "results": [
    { "ticker": "INTC", "ts": "2026-09-21T00:41:44.000Z", "kind": "estimate_revision",
      "payload": { "fiscal_date": "2026-09-30", "horizon": "fiscal quarter", "old_estimate": 0.12,
                   "new_estimate": 0.1, "change_pct": -16.67, "direction": "down", "analyst_count": 28 } }
  ]
}
```

## Notes

- This is [`GET /v2/events`](/docs/endpoints/events/query) with `kind=estimate_revision`; it has its own page because the payload is its own contract. The full query grammar lives there and applies here unchanged, including `join=state`.
- History starts on August 22, 2026, when we began keeping every consensus change. A revision is recorded when the consensus EPS itself moves; changes in coverage alone (analyst count, high, low) are not revisions.
- Latency: daily — the estimates refresh at the end of the evening ET ingestion pipeline. An unfiltered `/v2/events` stays the five corporate kinds, and event webhooks don't cover this kind yet.
- The surprise on each report (reported vs estimated EPS, `surprise_pct`) is on the [`earnings`](/docs/endpoints/events/earnings) kind.

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/events/estimate-revisions