Historical rating data is useful when you want to inspect how a company's financial score profile is structured over time. A current rating gives you one snapshot. Historical rating records let you review dated score outputs and see how profitability, leverage, valuation, or balance sheet-related fields appear in the endpoint response.
FMP's Historical Ratings endpoint returns dated rating snapshots for supported symbols. This endpoint should not be read as a history of individual brokerage recommendations. It is better understood as a structured record of FMP rating values and related financial score fields, including return on equity, return on assets, debt-to-equity, price-to-earnings, price-to-book, and DCF-related scoring.
That makes it a useful free API sandbox. On the Basic/free plan, Historical Ratings can be tested with endpoint-specific limits, including a maximum of 1 response per API call and symbol access limited to AAPL, TSLA, AMZN, and 84 more supported symbols. For an indie developer, student, analyst, or early product builder, that is enough to test authentication, response shape, field names, parsing logic, and whether the endpoint belongs in a larger workflow.
Key Takeaways
- The Historical Ratings endpoint returns FMP rating snapshots and financial score fields for supported symbols.
- The response includes fields such as rating, overallScore, discountedCashFlowScore, returnOnEquityScore, returnOnAssetsScore, debtToEquityScore, priceToEarningsScore, and priceToBookScore.
- The Basic/free plan can be used as a sandbox to test endpoint behavior, supported-symbol handling, response structure, and JSON parsing logic.
- On Basic/free access, Historical Ratings is limited to a maximum of 1 response per API call and a defined symbol set that includes AAPL, TSLA, AMZN, and 84 more supported symbols.
- Historical rating scores are research inputs. They should not be treated as stock-price forecasts or brokerage analyst recommendation history.
What Historical Rating Scores Show
The Historical Ratings endpoint returns rating records for a requested symbol. Each record includes the company symbol, the date of the rating snapshot, an overall rating, and several financial score fields.
This is useful when you want to inspect how a company's score profile is represented in FMP's data. A company may have an overall rating while individual score fields show different strengths or weaknesses underneath it. A profitability-related score may look strong, a leverage-related score may look weak, or valuation-related score fields may differ from the rest of the profile.
The endpoint is not a substitute for reading financial statements, reviewing estimates, or analyzing valuation directly. It gives developers and analysts a structured data point that can be used as one layer in a broader research or application workflow.
Step 1: Create a Free FMP API Key
Before making requests, create an FMP account and copy your API key from the developer dashboard. The key authenticates your request and lets you test supported endpoints from your own scripts, notebooks, API client, or application prototype.
For this workflow, the Basic/free plan is useful because it gives you a real testing environment. You can confirm that the endpoint authenticates, inspect the response fields, and test whether your code can parse the returned JSON. For Historical Ratings specifically, Basic/free access is constrained by endpoint limits, including a maximum of 1 response per API call and access to a defined list of supported sandbox symbols.
At the sandbox stage, the goal is to answer practical development questions:
- Can you authenticate successfully?
- Does the endpoint return the fields you expect?
- Can your script parse the JSON response?
- Can you store the result in a dataframe, database table, or dashboard component?
- Does this endpoint fit the workflow you are testing?
- Do you need broader symbol coverage, more records per call, or higher usage limits before scaling?
That makes the free plan useful for evaluating FMP before building a larger data workflow around it.
Step 2: Retrieve Historical Ratings for a Supported Symbol
With your API key ready, you can issue a direct HTTP GET request to test the endpoint. On Basic/free access, this should be treated as an endpoint validation step. You can test the request format, JSON structure, rating field, score fields, and supported-symbol behavior, but the endpoint is limited to a maximum of 1 response per API call.
Verified Request URL:
https://financialmodelingprep.com/stable/ratings-historical?symbol=AAPL&apikey=YOUR_API_KEY
Replace YOUR_API_KEY with your own key.
A sample response may look like this:
[
{
"symbol": "AAPL",
"date": "2026-06-10",
"rating": "B",
"overallScore": 3,
"discountedCashFlowScore": 3,
"returnOnEquityScore": 5,
"returnOnAssetsScore": 5,
"debtToEquityScore": 1,
"priceToEarningsScore": 2,
"priceToBookScore": 1
}
]
For a free-plan test, the important thing is not the size of the response. The useful test is whether you can make the request, confirm the schema, parse the fields, and decide whether the endpoint belongs in a larger workflow. If you need broader historical output, more symbols, or larger-scale testing, use the free test to validate the logic first, then match the workflow to the plan that supports the scale you need.
Step 3: Understand the Historical Rating Fields
The response is simple to parse because each record follows the same basic structure.
- symbol: The ticker requested in the API call.
- date: The date associated with the rating snapshot.
- rating: The letter rating returned for that record.
- overallScore: The numerical score associated with the overall rating.
- discountedCashFlowScore: The DCF-related score field returned in the rating snapshot.
- returnOnEquityScore: A score field tied to return on equity.
- returnOnAssetsScore: A score field tied to return on assets.
- debtToEquityScore: A score field tied to debt-to-equity.
- priceToEarningsScore: A score field tied to price-to-earnings.
- priceToBookScore: A score field tied to price-to-book.
These fields should be treated as rating output fields, not as raw financial statement values. If you want to understand why a score appears strong or weak, compare the rating record with the underlying financial statements, valuation data, or price history around the same period.
Step 4: What You Can Test With the Free Plan
The Basic/free plan is best used as a sandbox. It lets you test endpoint mechanics before deciding whether you need broader access.
For Historical Ratings, Basic/free access allows you to test the endpoint with specific constraints:
|
Free Plan Test Area |
What It Lets You Validate |
|
Authentication |
Whether your API key works in the request URL |
|
Supported symbols |
Whether your requested symbol is available in the free sandbox set |
|
Response shape |
Whether the endpoint returns the fields your app or script expects |
|
Field parsing |
Whether your code can parse rating, overallScore, and related score fields |
|
Data storage |
Whether the response fits your dataframe, database, or dashboard structure |
|
Workflow fit |
Whether Historical Ratings should be part of a broader research or product workflow |
For this endpoint, Basic/free access is limited to a maximum of 1 response per API call and a defined symbol set that includes AAPL, TSLA, AMZN, and 84 more supported symbols. That is still useful for validating the endpoint, but it should not be treated as full historical coverage or a production data feed.
If your workflow needs broader symbol coverage, more historical records, higher request volume, scheduled refreshes, or production reliability, use the free test to validate the logic first. Then scale the workflow with the plan that supports the coverage and usage you need.
Step 5: Use Historical Rating Scores With Other Financial Data
Historical rating scores become more useful when they are reviewed alongside the data that may explain them.
If a profitability-related score changes, compare that period with net income, margins, return on equity, return on assets, or other financial statement trends. If a leverage-related score weakens, review debt, equity, cash, and balance sheet movement. If valuation-related score fields move, compare them with historical prices, market cap, or valuation multiples over the same period.
Other FMP datasets can add context. If you want to compare rating changes with forward-looking expectations, analyst estimates and price target data can show whether external expectations were also changing around the same period. If you are building a market-data view, realtime market data and quotes can sit beside rating history to separate current market movement from historical financial score data.
The key is to keep the rating data in the right role. It is a structured historical input, not a complete explanation by itself.
Why Historical Rating Scores Are Useful
Historical rating scores give developers and analysts a clean way to test structured financial score data with a free API key. On the Basic/free plan, the value is in validating the endpoint: making the request, inspecting the fields, parsing the response, and deciding whether the data fits your app, dashboard, or research workflow.
For an indie developer, this can be a quick way to see whether FMP's API structure works for a screening tool or stock research feature. For an analyst, it can provide a simple test of the rating fields before combining them with statements, prices, estimates, or other datasets. For a product team, it can serve as a sandbox check before expanding into broader coverage or production use.
The strongest first project is simple: request Historical Ratings for one supported symbol, store the returned rating snapshot, inspect each score field, and decide how that structure would fit inside a larger workflow. If the endpoint fits, the next step is determining whether broader access is needed for more records, more symbols, or repeated refreshes.
Other Free API Workflows to Test
Once the historical ratings request is working, the same basic testing process can be reused across other FMP free API workflows. The pattern is simple: make the request, inspect the response, parse the fields, and decide whether the data supports the product or research workflow you want to build.
Useful next tests include:
- Retrieve historical sector and industry P/E ratios when you want to test aggregated valuation context.
- Retrieve analyst ratings when you want to compare a current rating snapshot with historical rating records.
- Retrieve historical stock grades when you want to test another time-series rating-style dataset.
- Retrieve stock grades when you want to test current grade fields for a supported symbol.
- Retrieve company share float data when you want to test company-level share structure data.
- Compare adjusted and unadjusted stock prices when you want to understand how splits and dividends affect price history.
- Analyze IPO filings and prospectuses when your workflow needs filing context for new market entrants.
- Track company headcount and workforce changes when you want to test another company-level time-series dataset.
Together, these pages give developers a practical sandbox path: start with one endpoint, confirm the response, then test adjacent datasets before building a broader FMP workflow.
FAQs
What does the Historical Ratings API return?
The endpoint returns a JSON array with rating snapshots for a requested symbol. Each record can include fields such as symbol, date, rating, overallScore, discountedCashFlowScore, returnOnEquityScore, returnOnAssetsScore, debtToEquityScore, priceToEarningsScore, and priceToBookScore.
Is this the same as analyst recommendation history?
No. This endpoint should not be treated as a history of individual brokerage recommendations. It returns FMP rating snapshots and related financial score fields. Analyst estimates, price targets, upgrades, downgrades, and recommendation datasets are separate workflows.
Is the Historical Ratings API available on the free tier?
Yes. Historical Ratings can be tested with a Basic/free API key. On Basic/free access, the endpoint is limited to a maximum of 1 response per API call and a defined symbol set that includes AAPL, TSLA, AMZN, and 84 more supported symbols.
What can I actually test for free?
You can test authentication, request formatting, supported-symbol behavior, response structure, field names, and JSON parsing. This is useful for validating whether the endpoint fits your app, dashboard, notebook, or research workflow before scaling.
Can I pull a full historical ratings time series on the free plan?
Not in the same way you would with broader access. The Basic/free plan shows a maximum of 1 response per API call for Historical Ratings, so it is best used to inspect the endpoint structure and test parsing logic. Larger historical workflows may require a plan with broader endpoint access.
Which symbols can I test with the free plan?
The Historical Ratings endpoint is symbol-limited on Basic/free access. The plan view shows access to AAPL, TSLA, AMZN, and 84 more supported symbols. Users should confirm the current supported symbol list inside their account before building a workflow around specific tickers.
Can I use historical rating scores to predict future stock prices?
No. Historical rating scores can support research, dashboards, data exploration, and workflow testing, but they should not be treated as a stock-price forecasting tool.
What does the historical DCF score measure?
The discountedCashFlowScore is the DCF-related score field returned in the historical rating snapshot. It should be treated as one component of the endpoint's rating output, not as a standalone DCF valuation.
What is a good first project with this endpoint?
A good first project is a small endpoint test for one supported symbol. Pull the response, store the returned rating snapshot, inspect overallScore and the individual score fields, and decide whether the structure fits the dashboard, table, or research workflow you want to build.
