Skip to main content
WSS
stream

Documentation Index

Fetch the complete documentation index at: https://benzinga-2-locadex-parallel-main.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterRequiredDescription
tokenYesYour Benzinga WebSocket API token (bz.production***)
tickersNoComma-separated list of ticker symbols (e.g., AAPL,MSFT)
isinsNoComma-separated list of ISINs to filter

​
Message Example

{
  "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

FieldDescription
epsActual earnings per share reported
eps_estAnalyst consensus EPS estimate
eps_surpriseDifference between actual and estimate
eps_surprise_percentSurprise as percentage of estimate
revenueActual revenue reported
revenue_estAnalyst consensus revenue estimate
importanceMarket significance (0-5, 5 = highest)

​
Message Actions

ActionDescription
created / CreatedNew earnings announcement
updated / UpdatedEarnings data modified
deleted / DeletedAnnouncement removed

​
Interactive Commands

CommandDescription
pingKeep connection alive (responds with pong)
replayReplay 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
Messages
token
type:httpApiKey

Benzinga WebSocket API token (bz.production***)

publish
type:string

Send action commands (ping, replay)

subscribe
type:object

Earnings event