Analyst tracker

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. 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.

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 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.