> ## 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. # Earnings Stream > Real-time earnings announcements and financial results. ## Overview Subscribe to real-time earnings announcements and receive instant updates on company financial results, including EPS, revenue, and earnings surprises. ### Key Features * **Real-time Earnings**: Get instant notifications of earnings announcements as they happen * **Comprehensive Data**: Includes EPS, revenue, estimates, actuals, and surprise metrics * **Filter by Security**: Subscribe to specific tickers or ISINs * **Earnings Periods**: Track Q1, Q2, Q3, Q4, and full-year (FY) results * **Importance Ratings**: 0-5 scale indicating market significance ### Use Cases * Build real-time earnings calendars and alerts * Track earnings surprises and beat/miss patterns * Monitor portfolio company earnings in real-time * Create earnings season dashboards * Automate trading strategies based on earnings results ## 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/earnings/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,MSFT`) | | `isins` | No | Comma-separated list of ISINs to filter | ## Message Example ```json theme={null} { "id": "839f1f45-fffe-4801-9284-11dae5c5dae4", "api_version": "websocket/v1", "kind": "data/v2.1/calendar/earnings", "data": { "action": "created", "id": "66fffe978f3f630001a2ea56", "timestamp": "2024-10-04T14:42:27Z", "content": { "ticker": "AAPL", "name": "Apple Inc.", "exchange": "NASDAQ", "date": "2024-10-04", "time": "16:00:00", "period": "Q4", "period_year": 2024, "eps": "1.47", "eps_est": "1.39", "eps_surprise": "0.08", "eps_surprise_percent": "5.76", "revenue": "89500000000", "revenue_est": "89280000000", "importance": 5 } } } ``` ### Key Fields | Field | Description | | ---------------------- | -------------------------------------- | | `eps` | Actual earnings per share reported | | `eps_est` | Analyst consensus EPS estimate | | `eps_surprise` | Difference between actual and estimate | | `eps_surprise_percent` | Surprise as percentage of estimate | | `revenue` | Actual revenue reported | | `revenue_est` | Analyst consensus revenue estimate | | `importance` | Market significance (0-5, 5 = highest) | ### Message Actions | Action | Description | | --------------------- | ------------------------- | | `created` / `Created` | New earnings announcement | | `updated` / `Updated` | Earnings data modified | | `deleted` / `Deleted` | Announcement removed | ## Interactive Commands | Command | Description | | -------- | -------------------------------------------- | | `ping` | Keep connection alive (responds with `pong`) | | `replay` | Replay up to the last 100 cached messages | ## Best Practices * **Deduplication**: Use the `id` field to prevent duplicate processing * **Importance Filter**: Focus on high-importance (4-5) earnings for major market impact * **Surprise Alerts**: Set thresholds for significant earnings surprises * **Timing**: Note that `time` field uses 24-hour format in EST/EDT ## AsyncAPI ````yaml asyncapi/calendar-earnings-stream.yml calendarEarnings id: calendarEarnings title: Calendar earnings description: Send action commands; receive real-time earnings updates servers: - id: production protocol: wss host: api.benzinga.com/api/v2.1/calendar/earnings bindings: [] variables: [] address: stream parameters: [] bindings: [] operations: - &ref_2 id: calendarEarnings.publish title: Calendar earnings.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: calendarEarnings - &ref_3 id: calendarEarnings.subscribe title: Calendar earnings.subscribe description: Receive real-time earnings data type: send messages: - &ref_5 id: subscribe contentType: application/json payload: - name: subscribe description: Earnings 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/earnings 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 earnings 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 identifier for the earnings required: false - name: date type: string description: Announced Date on Calendar required: false - name: date_confirmed type: integer description: If the report date was confirmed (1/0) required: false - name: time type: string description: Announced Time on Calendar (24hr format) required: false - name: ticker type: string description: Ticker Symbol (F, MSFT, etc...) 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 security required: false - name: currency type: string description: Currency the data is denominated in required: false - name: period type: string description: Period of the earnings actual enumValues: - Q1 - Q2 - Q3 - Q4 - FY - H1 - H2 required: false - name: period_year type: integer description: Period Year of the earnings actual required: false - name: eps_type type: string description: EPS Type enumValues: - Adj - GAAP - FFO required: false - name: eps type: string description: Comparable and Adjusted Earnings Per Share required: false - name: eps_est type: string description: Adjusted EPS Consensus Aggregate Analyst Estimate required: false - name: eps_prior type: string description: Adjusted EPS from Prior Period required: false - name: eps_surprise type: string description: EPS deviation from estimate required: false - name: eps_surprise_percent type: string description: Deviation from estimate as a percentage required: false - name: revenue_type type: string description: Revenue Type enumValues: - Adj - GAAP - FFO required: false - name: revenue type: string description: Revenue required: false - name: revenue_est type: string description: Revenue estimate required: false - name: revenue_prior type: string description: Revenue value for previous period required: false - name: revenue_surprise type: string description: Revenue deviation from estimate required: false - name: revenue_surprise_percent type: string description: Deviation from estimate as a percentage required: false - name: importance type: integer description: Importance of the event to the market (0-5) required: false - name: notes type: string description: Additional notes provided by the Benzinga Newsdesk required: false - name: updated type: integer description: Last updated timestamp (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/earnings 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 earnings 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 identifier for the earnings x-parser-schema-id: date: type: string format: date description: Announced Date on Calendar x-parser-schema-id: date_confirmed: type: integer description: If the report date was confirmed (1/0) x-parser-schema-id: time: type: string description: Announced Time on Calendar (24hr format) x-parser-schema-id: ticker: type: string description: Ticker Symbol (F, MSFT, etc...) 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 security x-parser-schema-id: currency: type: string description: Currency the data is denominated in x-parser-schema-id: period: type: string enum: - Q1 - Q2 - Q3 - Q4 - FY - H1 - H2 description: Period of the earnings actual x-parser-schema-id: period_year: type: integer description: Period Year of the earnings actual x-parser-schema-id: eps_type: type: string enum: - Adj - GAAP - FFO description: EPS Type x-parser-schema-id: eps: type: string description: Comparable and Adjusted Earnings Per Share x-parser-schema-id: eps_est: type: string description: Adjusted EPS Consensus Aggregate Analyst Estimate x-parser-schema-id: eps_prior: type: string description: Adjusted EPS from Prior Period x-parser-schema-id: eps_surprise: type: string description: EPS deviation from estimate x-parser-schema-id: eps_surprise_percent: type: string description: Deviation from estimate as a percentage x-parser-schema-id: revenue_type: type: string enum: - Adj - GAAP - FFO description: Revenue Type x-parser-schema-id: revenue: type: string description: Revenue x-parser-schema-id: revenue_est: type: string description: Revenue estimate x-parser-schema-id: revenue_prior: type: string description: Revenue value for previous period x-parser-schema-id: revenue_surprise: type: string description: Revenue deviation from estimate x-parser-schema-id: revenue_surprise_percent: type: string description: Deviation from estimate as a percentage x-parser-schema-id: importance: type: integer minimum: 0 maximum: 5 description: Importance of the event to the market (0-5) x-parser-schema-id: notes: type: string description: Additional notes provided by the Benzinga Newsdesk x-parser-schema-id: updated: type: integer format: int64 description: Last updated timestamp (UTC) x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: title: Subscribe description: Earnings event example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe - id: x-parser-message-name value: EarningsMessage bindings: [] extensions: *ref_1 sendOperations: - *ref_2 receiveOperations: - *ref_3 sendMessages: - *ref_4 receiveMessages: - *ref_5 extensions: - id: x-parser-unique-object-id value: calendarEarnings securitySchemes: - id: tokenAuth name: token type: httpApiKey description: Benzinga WebSocket API token (bz.production***) in: query extensions: [] ````