> ## Documentation Index > Fetch the complete documentation index at: https://docs.benzinga.com/llms.txt > Use this file to discover all available pages before exploring further. # Ratings Stream > Real-time analyst ratings and price target changes. ## Overview Subscribe to real-time analyst rating changes and price target updates. Monitor upgrades, downgrades, initiations, and price target adjustments as they happen. ### Key Features * **Real-time Ratings**: Get instant notifications of analyst rating changes * **Price Targets**: Track current and prior price targets with adjustments * **Analyst Details**: Includes analyst name, firm, and historical accuracy metrics * **Action Classification**: Upgrades, downgrades, maintains, initiates, reiterates * **Filter by Security**: Subscribe to specific tickers or ISINs ### Use Cases * Build real-time rating change alerts and notifications * Track analyst firm performance and accuracy * Monitor price target consensus shifts * Create rating upgrade/downgrade dashboards * Automate trading strategies based on analyst actions ## Quick Start Use the interactive WebSocket tester above to connect and test the stream in real-time. ### Connection URL ``` wss://api.benzinga.com/api/v2.1/calendar/ratings/stream?token=YOUR_TOKEN ``` ### Query Parameters | Parameter | Required | Description | | --------- | -------- | ---------------------------------------------------------- | | `token` | Yes | Your Benzinga WebSocket API token (bz.production\*\*\*) | | `tickers` | No | Comma-separated list of ticker symbols (e.g., `AAPL,TSLA`) | | `isins` | No | Comma-separated list of ISINs to filter | ## Message Example ```json theme={null} { "id": "e9e75b31-604e-422c-a532-362725b2d59d", "api_version": "websocket/v1", "kind": "data/v2.1/calendar/ratings", "data": { "action": "created", "id": "66fffdc08f3f630001a2ea51", "timestamp": "2024-10-04T19:21:06Z", "content": { "ticker": "AAPL", "name": "Apple", "exchange": "NASDAQ", "date": "2024-10-04", "time": "10:37:52", "action_company": "Upgrades", "rating_current": "Buy", "rating_prior": "Neutral", "pt_current": "200.00", "pt_prior": "180.00", "analyst": "Goldman Sachs", "firm_id": "57f832ab6b87f600016fa383", "importance": 4 } } } ``` ### Rating Actions | Action | Description | | ------------ | ------------------------------------- | | `Upgrades` | Rating improved (e.g., Neutral → Buy) | | `Downgrades` | Rating lowered (e.g., Buy → Hold) | | `Maintains` | Rating unchanged | | `Initiates` | First rating coverage | | `Reiterates` | Confirms existing rating | ### Message Actions | Action | Description | | --------------------- | -------------------- | | `created` / `Created` | New rating published | | `updated` / `Updated` | Rating modified | | `deleted` / `Deleted` | Rating removed | ## Interactive Commands | Command | Description | | -------- | -------------------------------------------- | | `ping` | Keep connection alive (responds with `pong`) | | `replay` | Replay up to the last 100 cached messages | ## Best Practices * **Track Changes**: Compare `rating_current` vs `rating_prior` for upgrade/downgrade detection * **Price Target Movement**: Monitor `pt_current` vs `pt_prior` for target changes * **Analyst Reputation**: Consider firm importance and historical accuracy * **Importance Filter**: Focus on high-importance (4-5) ratings for major impact ## AsyncAPI ````yaml asyncapi/calendar-ratings-stream.yml calendarRatings id: calendarRatings title: Calendar ratings description: Send action commands; receive real-time ratings updates servers: - id: production protocol: wss host: api.benzinga.com/api/v2.1/calendar/ratings bindings: [] variables: [] address: stream parameters: [] bindings: [] operations: - &ref_2 id: calendarRatings.publish title: Calendar ratings.publish description: Send commands to the server type: receive messages: - &ref_4 id: publish contentType: text/plain payload: - type: string enum: &ref_0 - ping - replay description: Send action commands (ping, replay) x-parser-schema-id: name: publish headers: [] jsonPayloadSchema: type: string enum: *ref_0 description: Action to perform (ping for heartbeat, replay for message history) x-parser-schema-id: title: Publish description: Send action commands (ping, replay) example: '{}' bindings: [] extensions: - id: x-parser-unique-object-id value: publish - id: x-parser-message-name value: ActionRequest bindings: [] extensions: &ref_1 - id: x-parser-unique-object-id value: calendarRatings - &ref_3 id: calendarRatings.subscribe title: Calendar ratings.subscribe description: Receive real-time ratings data type: send messages: - &ref_5 id: subscribe contentType: application/json payload: - name: subscribe description: Analyst ratings event type: object properties: - name: id type: string description: Unique UUID for the websocket response required: true - name: api_version type: string description: Websocket API version enumValues: - websocket/v1 required: true - name: kind type: string description: Websocket connection stream type enumValues: - data/v2.1/calendar/ratings required: true - name: data type: object required: true properties: - name: action type: string description: Websocket data action enumValues: - created - updated - deleted - Created - Updated - Deleted required: false - name: id type: string description: Data ID for the rating required: false - name: timestamp type: string description: Timestamp of the data required: false - name: content type: object required: false properties: - name: id type: string description: Unique ID of this entry required: false - name: date type: string description: Date for rating required: false - name: time type: string description: Time for rating required: false - name: ticker type: string description: >- Ticker symbol of the company that is the subject of the rating required: false - name: exchange type: string description: Exchange (NYSE, NASDAQ, etc...) required: false - name: isin type: string description: International Securities Identification Number required: false - name: cusip type: string description: CUSIP identifier required: false - name: name type: string description: Name of the company that is the subject of the rating required: false - name: currency type: string description: Currency the data is denominated in required: false - name: action_pt type: string description: >- Description of the change in price target from the firm's last price target required: false - name: action_company type: string description: >- Description of the change in rating from the firm's last rating required: false - name: rating_current type: string description: The analyst's current rating for the company required: false - name: pt_current type: string description: Analyst's current price target required: false - name: adjusted_pt_current type: string description: >- Analyst's current price target, adjusted for stock splits and dividends required: false - name: rating_prior type: string description: Prior analyst rating for the company required: false - name: pt_prior type: string description: Analyst's prior price target required: false - name: adjusted_pt_prior type: string description: >- Analyst's prior price target, adjusted for stock splits and dividends required: false - name: url type: string description: >- URL for the analyst ratings page for this ticker on Benzinga.com required: false - name: url_calendar type: string description: >- URL for the analyst ratings page for this ticker on Benzinga.com required: false - name: url_news type: string description: >- URL for the analyst ratings news articles for this ticker on Benzinga.com required: false - name: analyst type: string description: Name of the analyst firm that published the rating required: false - name: analyst_id type: string description: ID of the analyst required: false - name: analyst_name type: string description: Name of the analyst (person) that published the rating required: false - name: firm_id type: string description: Unique identifier for the firm required: false - name: importance type: integer description: >- Subjective basis of how important the event is to the market (5 = High) required: false - name: notes type: string description: >- Additional notes provided by the Benzinga Newsdesk where applicable required: false - name: updated type: integer description: Last updated timestamp in UTC required: false headers: [] jsonPayloadSchema: type: object required: - id - api_version - kind - data properties: id: type: string format: uuid description: Unique UUID for the websocket response x-parser-schema-id: api_version: type: string enum: - websocket/v1 description: Websocket API version x-parser-schema-id: kind: type: string enum: - data/v2.1/calendar/ratings description: Websocket connection stream type x-parser-schema-id: data: type: object required: - action - id - content - timestamp properties: action: type: string enum: - created - updated - deleted - Created - Updated - Deleted description: Websocket data action x-parser-schema-id: id: type: string description: Data ID for the rating x-parser-schema-id: timestamp: type: string format: date-time description: Timestamp of the data x-parser-schema-id: content: type: object required: - id - date - ticker - exchange - name properties: id: type: string description: Unique ID of this entry x-parser-schema-id: date: type: string format: date description: Date for rating x-parser-schema-id: time: type: string description: Time for rating x-parser-schema-id: ticker: type: string description: >- Ticker symbol of the company that is the subject of the rating x-parser-schema-id: exchange: type: string description: Exchange (NYSE, NASDAQ, etc...) x-parser-schema-id: isin: type: string description: International Securities Identification Number x-parser-schema-id: cusip: type: string description: CUSIP identifier x-parser-schema-id: name: type: string description: Name of the company that is the subject of the rating x-parser-schema-id: currency: type: string description: Currency the data is denominated in x-parser-schema-id: action_pt: type: string description: >- Description of the change in price target from the firm's last price target x-parser-schema-id: action_company: type: string description: >- Description of the change in rating from the firm's last rating x-parser-schema-id: rating_current: type: string description: The analyst's current rating for the company x-parser-schema-id: pt_current: type: string description: Analyst's current price target x-parser-schema-id: adjusted_pt_current: type: string description: >- Analyst's current price target, adjusted for stock splits and dividends x-parser-schema-id: rating_prior: type: string description: Prior analyst rating for the company x-parser-schema-id: pt_prior: type: string description: Analyst's prior price target x-parser-schema-id: adjusted_pt_prior: type: string description: >- Analyst's prior price target, adjusted for stock splits and dividends x-parser-schema-id: url: type: string format: uri description: >- URL for the analyst ratings page for this ticker on Benzinga.com x-parser-schema-id: url_calendar: type: string format: uri description: >- URL for the analyst ratings page for this ticker on Benzinga.com x-parser-schema-id: url_news: type: string format: uri description: >- URL for the analyst ratings news articles for this ticker on Benzinga.com x-parser-schema-id: analyst: type: string description: Name of the analyst firm that published the rating x-parser-schema-id: analyst_id: type: string description: ID of the analyst x-parser-schema-id: analyst_name: type: string description: Name of the analyst (person) that published the rating x-parser-schema-id: firm_id: type: string description: Unique identifier for the firm x-parser-schema-id: importance: type: integer minimum: 0 maximum: 5 description: >- Subjective basis of how important the event is to the market (5 = High) x-parser-schema-id: notes: type: string description: >- Additional notes provided by the Benzinga Newsdesk where applicable x-parser-schema-id: updated: type: integer format: int64 description: Last updated timestamp in UTC x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: title: Subscribe description: Analyst ratings event example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe - id: x-parser-message-name value: RatingsMessage bindings: [] extensions: *ref_1 sendOperations: - *ref_2 receiveOperations: - *ref_3 sendMessages: - *ref_4 receiveMessages: - *ref_5 extensions: - id: x-parser-unique-object-id value: calendarRatings securitySchemes: - id: tokenAuth name: token type: httpApiKey description: Benzinga WebSocket API token (bz.production***) in: query extensions: [] ````