/analyst-tracker

name: analyst-tracker
description: Track sell-side analyst positioning on a name via Benzinga Analyst Ratings. Pulls every rating event over the lookback window, classifies each as upgrade / downgrade / initiation / reiteration / drop-coverage / PT-change, aggregates the latest rating and price target per firm, and reports the current consensus (median PT across firms plus buy/hold/sell distribution). Uses Massive's built-in Benzinga integration. Requires Stocks Basic + Benzinga Analyst Ratings entitlement.

analyst-tracker

You hand over a ticker. The skill pulls every analyst rating event Benzinga has on record over the lookback window, buckets each firm's raw rating string to a standard scale (buy / hold / sell), classifies the event (upgrade / downgrade / initiation / reiteration / PT-change / drop-coverage), aggregates the latest per firm, and reports the consensus median price target plus buy/hold/sell distribution.

This is the sell-side lens the repo was missing. Pairs cleanly with `insider-flow` (internal vs external sentiment on the same name) and `guidance-tracker` (analyst reaction vs management's own projections).

When to invoke

• A PM asks "how is sell-side positioning shifting on NVDA?"
• Fundamental analyst wants to see who's changed their view and by

how much

• Screening for consensus PT vs current price gap as a mean-reversion

cue

• The user says "analyst ratings", "sell-side", "upgrades",

"downgrades", "price target", "consensus"

Not for: analyst quality or track record (Benzinga returns the ratings, not the historical accuracy). Not for real-time (Benzinga updates within minutes but this is not a tick feed).

What you need

• A ticker (`--ticker`, required)
• `MASSIVE_API_KEY` exported
• Stocks Basic plan + **Benzinga Analyst Ratings** entitlement.

The endpoint returns NOT_AUTHORIZED without it; skill emits a clean tier caveat rather than a raw error.

Optional:

• `--lookback-days` (default 180): calendar-day window back from today.

What you get back

Two output layers from one run.

**Layer 1: canonical JSON** matching [`output-schema.json`](./output-schema.json). Per-event: `date`, `firm`, `analyst`, `rating_raw`, `rating_bucket` (buy / hold / sell / other / unknown), `previous_rating_raw`, `event_label` (upgrade / downgrade / initiation / reiteration / price_target_change_only / drop_coverage / other), `price_target`, `previous_price_target`, `pt_direction`, `pt_delta_pct`. Top-level `summary` with event counts, per-firm latest rating distribution, and consensus median / low / high price target.

**Layer 2: rendered note**. Header + summary line + rating distribution + consensus PT, timeline of the last 25 events, one-line Take. See [`references/rendering.md`](./references/rendering.md).

How it works

1. **Pull ratings** via `GET /benzinga/v1/ratings?ticker={T}&date.gte={D}&limit=1000&sort=date.desc`. 2. **Bucket rating strings** using standard synonym sets. Buy set: buy, strong buy, outperform, overweight, positive, add, accumulate, top pick. Hold set: hold, neutral, market perform, equal-weight, in-line. Sell set: sell, underperform, underweight, reduce, negative. Anything else lands in "other". 3. **Classify each event.** Rating actions like initiates_coverage_on, upgrade, downgrade, maintains, reiterates map directly. When Benzinga omits the action but the bucket changed, infer upgrade/downgrade from the bucket transition. 4. **Detect price-target-only changes.** Reiterated rating + changed PT gets labeled `price_target_change_only`. 5. **Aggregate latest per firm.** Because ratings come newest-first, the first row per firm gives the latest state. Median across firms is the consensus PT; buy/hold/sell counts describe the distribution.

Foundations used

• [`massive-api-patterns`](../massive-api-patterns) for REST auth,

retry, and pagination.

Output mode: note

Narrative note with a timeline. A single-name analyst history is typically 20-100 events over 6 months; note format reads better than a wide table.

Endpoints used

• `GET /benzinga/v1/ratings?ticker={T}&date.gte={D}` — every rating

event for the ticker in the window.

Doesn't handle (yet)

• **Firm track record.** No historical accuracy metric per firm or

analyst.

• **Consensus rating vs consensus PT reconciliation.** Firms often

raise PT while keeping a Hold rating (or vice versa); these are reported separately, not reconciled.

• **Guidance overlay.** Pair with `guidance-tracker` for a workflow

composite: "did the analyst move after management guided?"

• **Bulls Bears Say text.** The endpoint returns rating actions and

PTs; the narrative from Bulls Bears Say is a separate endpoint.

• **Peer comparison.** No "is NVDA's PT delta above peer set median?"

Queued as a composite.

These are clean PR extensions. Output schema is forward-compatible.