Skip to main content

​
Overview

The yf_ticker_upgrades_downgrades tool provides a detailed history of analyst rating changes, including upgrades, downgrades, initiations, and reiterations.

​
yf_ticker_upgrades_downgrades

Retrieves the complete history of analyst rating actions for a ticker.

​
Parameters

ParameterTypeRequiredDescription
tickerstringYesTicker symbol (e.g., “AAPL”)
response_formatstringNoOutput format: “json” (default) or “markdown”
preview_limitnumberNoMax rows to preview (1-200, default: 25)
saveobjectNoSave options with format (“csv” or “json”) and optional filename

​
Response Data

Returns a DataFrame with columns typically including:
  • GradeDate - Date of the rating action
  • Firm - Name of the analyst firm
  • ToGrade - New rating assigned
  • FromGrade - Previous rating (if applicable)
  • Action - Type of action (e.g., “up”, “down”, “init”, “main”, “reit”)

​
Action Types

ActionDescription
upUpgrade - firm raised its rating
downDowngrade - firm lowered its rating
initInitiated coverage - first rating from this firm
mainMaintained - reaffirmed existing rating
reitReiterated - restated rating without change

​
Example

{
  "ticker": "TSLA",
  "response_format": "markdown"
}

​
Sample Response (Markdown)

index | GradeDate | Firm | ToGrade | FromGrade | Action
--- | --- | --- | --- | --- | ---
0 | 2024-01-15 | Morgan Stanley | Overweight | Equal-Weight | up
1 | 2024-01-10 | Goldman Sachs | Buy | | init
2 | 2023-12-20 | JP Morgan | Neutral | Overweight | down
3 | 2023-12-15 | Bank of America | Buy | Buy | main

​
Understanding Rating Grades

Different firms use different terminology for their ratings. Common rating scales include:

​
Five-Tier Scale

  • Strong Buy / Buy / Hold / Sell / Strong Sell

​
Three-Tier Scale

  • Buy (or Overweight) / Hold (or Neutral/Equal-Weight) / Sell (or Underweight)

​
Firm-Specific Terms

  • Outperform ≈ Buy
  • Market Perform ≈ Hold
  • Underperform ≈ Sell
  • Overweight ≈ Buy (relative to benchmark)
  • Equal-Weight ≈ Hold
  • Underweight ≈ Sell (relative to benchmark)

​
Use Cases

​
Tracking Recent Activity

Identify which firms have recently changed their stance: 
{
  "ticker": "NVDA",
  "response_format": "markdown",
  "preview_limit": 10
}
Focus on the most recent 10 actions to understand current momentum.

​
Analyzing Firm Behavior

Filter historical data to see how specific firms have rated the stock over time: 
{
  "ticker": "AAPL",
  "response_format": "json",
  "save": {
    "format": "csv",
    "filename": "aapl-rating-history.csv"
  }
}
Then analyze the CSV to identify patterns by firm.

​
Pre-Earnings Positioning

Check if analysts are positioning ahead of earnings by upgrading/downgrading: 
{
  "ticker": "META",
  "response_format": "markdown",
  "preview_limit": 20
}
Cross-reference dates with earnings announcements.

​
Sentiment Shifts

Monitor the ratio of upgrades to downgrades to gauge shifting sentiment:
  1. Retrieve full history
  2. Count actions by type
  3. Track whether recent activity is net positive or negative

​
Interpreting Rating Changes

​
Upgrade Significance

  • Positive signal: Analyst increased confidence in the stock
  • May indicate: Improved fundamentals, raised estimates, or better outlook
  • Impact: Often correlates with positive price momentum

​
Downgrade Significance

  • Negative signal: Analyst reduced confidence
  • May indicate: Deteriorating fundamentals, lowered estimates, or concerns
  • Impact: Often correlates with negative price momentum

​
Initiation Coverage

  • New coverage: Firm begins tracking the stock
  • Often bullish: Firms typically initiate with Buy/Overweight ratings
  • Visibility boost: Can increase institutional awareness

​
Maintained/Reiterated Ratings

  • Confirmation: Firm reaffirms its view
  • Context matters: May be noteworthy if issued after major news or earnings
  • Less impactful: Generally has minimal price impact

​
Combining with Other Tools

For comprehensive analyst analysis, combine with:

​
yf_ticker_recommendations

Get the full historical recommendation data (similar but may have different data structure).

​
yf_ticker_recommendations_summary

See aggregated counts of current recommendations.

​
yf_ticker_analyst_price_targets

Understand the price targets associated with these ratings.

​
yf_ticker_eps_revisions

Correlate rating changes with estimate revisions.

​
Example Workflow

// Step 1: Get recent upgrades/downgrades
{
  "ticker": "MSFT",
  "response_format": "markdown",
  "preview_limit": 15
}

// Step 2: Check if estimate revisions align with rating changes
{
  "ticker": "MSFT",
  "response_format": "markdown"
} // using yf_ticker_eps_revisions

// Step 3: Review current consensus and price targets
{
  "ticker": "MSFT",
  "response_format": "json"
} // using yf_ticker_analyst_price_targets

​
Notes

  • Not all rating changes appear immediately (may have data lag)
  • Some firms issue ratings without prior coverage (FromGrade will be empty)
  • Historical data depth varies by ticker
  • Ratings reflect analyst opinions and should be one input among many
  • Some firms may have proprietary rating scales not immediately comparable

​
Best Practices

  1. Look for clusters: Multiple downgrades in a short period may be more significant than a single change
  2. Consider the source: Ratings from top-tier firms often have more market impact
  3. Check the date: Recent actions are more relevant than old ratings
  4. Cross-reference: Combine with price action, estimates, and other analyst data
  5. Watch for reversals: Firms that frequently flip ratings may be less reliable

Build docs developers (and LLMs) love

Get started for freeTalk to us