Analyst recommendations for popular stocks shift constantly as quarterly earnings numbers drop and business conditions evolve. Relying strictly on a single point-in-time rating ignores how the broader market consensus is trending over time.
Tracking historical stock grades allows developers, analysts, and students to see how the overall volume of analyst opinions changes across historical cycles. This guide walks you through setting up a free account, querying the historical stock grades endpoint, and reading the response data to track consensus trends.
Key Takeaways
- Track Consensus Shifts: Tracking historical grades reveals whether a shift in market sentiment happens instantly or trends gradually over several months.
- Granular Distribution: Examining the full distribution of buy, hold, and sell counts provides a clearer view of market sentiment than a single summary rating.
- Sandbox Testing: A free API key allows you to safely test endpoint functionality, JSON structures, and data parsing before building production workflows.
- Research Input Only: Historical stock grades serve as an analytical input to measure market sentiment, not a standalone tool to predict stock performance.
What Historical Stock Grades Show
Historical stock grades aggregate the total number of analyst recommendations for a specific equity over time. Instead of looking at a single firm's opinion, this data gives you a macro view of the entire brokerage community's expectations.
By analyzing the historical distribution of these grades, you can observe shifts in sentiment across consecutive quarters. For example, you can track whether institutional analysts are quietly moving their recommendations from "Strong Buy" down to "Hold" long before a major public downgrade hits the news cycle.
Step 1: Create a Free FMP API Key
Before making programmatic requests, you need to generate a unique API key to authenticate your data feed.
- Go to the Financial Modeling Prep pricing page to view the data tiers.
- Select the Free Plan option to open a baseline account.
- Complete the registration using a valid email address—no credit card or billing details are required.
- Open your developer dashboard and copy your personal API key from the top of the page.
Step 2: Retrieve Historical Stock Grades for a Supported Symbol
With your key ready, you can issue a direct HTTP GET request to pull the time-series grading data. On the free tier, you can test endpoint behavior using highly liquid sandbox symbols like Apple (AAPL).
Verified Request URLHTTP
https://financialmodelingprep.com/stable/grades-historical?symbol=AAPL&apikey=YOUR_API_KEY
Sample JSON Response
When you call the endpoint, the API returns a structured array of JSON objects containing the historical distribution of recommendations:
JSON Response:
[
{
"date": "2026-06-01",
"symbol": "AAPL",
"strongBuy": 7,
"buy": 23,
"hold": 15,
"sell": 1,
"strongSell": 2
},
{
"date": "2026-05-01",
"symbol": "AAPL",
"strongBuy": 7,
"buy": 25,
"hold": 14,
"sell": 1,
"strongSell": 2
}
]
Step 3: Read the Historical Grade Distribution
The JSON response breaks down analyst consensus into precise, easy-to-parse key-value pairs:
- date & symbol: Confirms the exact date of the recorded distribution snapshot and references the requested equity ticker.
- strongBuy & buy: Records the absolute count of optimistic, bullish institutional recommendations. For instance, in the June snapshot above, there are 7 strong buy and 23 buy entries.
- hold: Identifies the volume of neutral or defensive ratings where analysts advise maintaining existing positions.
- sell & strongSell: Measures bearish sentiment, highlighting the number of analysts actively recommending a reduction in exposure.
Comparing the monthly blocks tells you how fast consensus momentum is moving. Looking at the sample data above, the total number of standard "buy" recommendations dropped from 25 to 23 between May and June, signaling a minor deceleration in bullish sentiment.
Step 4: Understand What You Can Test for Free
The free tier is built specifically for prototyping, testing data frames, and configuring your data ingestion scripts. When working with a free account, keep the following technical boundaries in mind:
- Supported Symbol Sandbox: Free queries are restricted to a select list of major, highly liquid equities and indexes, such as AAPL, TSLA, MSFT, NVDA, and SPY. Querying a symbol outside this list will return a parameter limitation error.
- Payload Limits: The free plan caps the historical depth at a maximum of 10 records per API call. This gives you enough data to test your parsing logic but is not intended for multi-year historical backtesting.
- Rate Limits: Free accounts feature daily call limits designed for development testing rather than live production screening or scaling enterprise applications.
Step 5: Use Historical Grades With Other Financial Data
To build more comprehensive research workflows, historical stock grades should be paired with adjacent datasets. This helps verify if shifts in analyst counts align with adjustments in other valuation metrics.
For example, you can combine the historical consensus log with tools that let you access analyst estimates programmatically. Cross-referencing a dropping buy count against target price revisions allows you to see if analysts are lowering their long-term expectations or simply adjusting short-term grades.
Additionally, tracking these revisions against actual historical timelines requires reliable end-of-day closes. Blending monthly sentiment trends with standard real-time stock market data ensures you map consensus shifts to the correct operational market hours.
Explore More Ways to Leverage a Free Account
If you are developing a financial app or learning to work with data feeds, a free FMP account allows you to explore multiple endpoints beyond stock grades. Check out these step-by-step guides to expand your project:
- Track Executive Teams and Leadership Changes With a Free API - Learn how to track corporate governance trends and executive turnover.
- Pull Cryptocurrency Prices Using a Free API - Connect to digital asset feeds and ingest live crypto price trends.
- Pull Clean Company Profiles Using a Free API - Extract foundational company data, including sector information, description metadata, and industry categories.
Frequently Asked Questions
What metrics are delivered by the Historical Stock Grades API?
The endpoint delivers a structured chronological log of recommendation counts, dividing market consensus into clear categories: Strong Buy, Buy, Hold, Sell, and Strong Sell tallies.
How does the free tier limit the stock grades endpoint?
The free tier limits your queries to a baseline sandbox of liquid symbols (like AAPL and TSLA) and caps the output payload at a maximum of 10 historical records per request.
Can this historical grading data be used to predict future performance?
No. The historical grades feed provides a retrospective audit of past analyst distribution counts. It is used to analyze market sentiment trends and consensus history, not to forecast future stock prices.
Why do some stock symbols return empty grading histories?
Analyst coverage depends entirely on market capitalization and institutional interest. Smaller stocks or newly listed companies often have sparse grading logs because fewer brokerage firms publish active recommendations for them.
How do I handle the 10-response limit on the free plan?
The 10-response limit is designed to let you test your code logic. To build deeper historical timelines across multiple years for comprehensive research, your workflow will require moving beyond the free tier limits.
What is the difference between an analyst rating and a stock grade distribution?
An analyst rating is typically a single firm's opinion (e.g., "Buy"). A stock grade distribution aggregates all active ratings across the entire brokerage community, giving you a complete count of how many analysts share that same view.
