# Stock Earnings Calendar - Estimates, Actuals & Surprises (`michael_b/stock-earnings-calendar`) Actor Get upcoming and recent US stock earnings by date range. Returns EPS estimates, actuals, surprise percentages, YoY growth, sector, and market cap. Filter by tickers, market cap, or sector. Export as JSON, CSV, or Excel. Flat schema for trading systems, dashboards, and AI agents via MCP. - **URL**: https://apify.com/michael\_b/stock-earnings-calendar.md - **Developed by:** [Michal BΓΊci](https://apify.com/michael_b) (community) - **Categories:** MCP servers, Agents, Developer tools - **Stats:** 1 total users, 1 monthly users, 75.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.50 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Stock Earnings Calendar - Estimates, Actuals & Surprises Get upcoming and recent US stock earnings reports by date range. Returns EPS estimates, actuals, surprise percentages, YoY growth, sector, and market cap. Filter by tickers, market cap, or sector in a single query. ### **What is the Stock Earnings Calendar?** This actor pulls earnings calendar data from public financial sources for all US-listed stocks. It returns a flat, structured dataset covering both **upcoming earnings** (with consensus EPS estimates) and **past earnings** (with actuals and surprise percentages), all in the same schema. Unlike per-ticker lookup tools, this actor lets you query by **date range with filters**. Get "all Technology stocks reporting this week with market cap above $2B" in one call instead of stitching together multiple APIs. Export results as JSON, CSV, or Excel, integrate via the Apify API, or connect to AI agents via MCP. ### **Why use this earnings calendar?** Most earnings data tools have one of these problems: - **Per-ticker only** - You need to already know which tickers to check. No way to scan the full market. - **No filters** - You get hundreds of micro-caps and SPACs you'll never trade. No market cap or sector filtering. - **Forward OR backward, not both** - Calendar tools show upcoming dates. History tools show past results. They don't share a schema. - **Messy nested schemas** - Deeply nested JSON with `raw`/`fmt`/`longFmt` for every field. Impossible for AI agents to parse reliably. - **Previous quarter missing** - You get the current estimate but not last year's actual. Trend detection requires a second API call. This actor solves all five. One call, flat schema, bi-directional dates, with filters and historical context built in. ### **How to get stock earnings data by date range** 1. Go to the [Stock Earnings Calendar](https://apify.com/michael_b/stock-earnings-calendar) actor page 2. Optionally set a date range, tickers, market cap filter, or sector 3. Click **Start** 4. Download results as **JSON, CSV, or Excel**, or access via the Apify API Default date range is 3 days back to 14 days forward, covering the most common use case: checking recent surprises and upcoming reports. ### **Input** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `dateFrom` | string | 3 days ago | Start date (YYYY-MM-DD). Up to 365 days back. | | `dateTo` | string | 14 days ahead | End date (YYYY-MM-DD). Up to 365 days forward. | | `tickers` | string | all | Comma-separated tickers, e.g. `AAPL, TSLA, MSFT` | | `marketCapMin` | integer | 0 | Minimum market cap in millions USD. `500` = $500M+. | | `sector` | string | all | Sector filter. Pick from dropdown: Technology, Finance, Health Care, Energy, etc. | ```json { "dateFrom": "2026-04-07", "dateTo": "2026-04-18", "marketCapMin": 1000, "sector": "Technology" } ```` ### **Output** ```json { "ticker": "AAPL", "companyName": "Apple Inc.", "sector": "Technology", "industry": "Computer Manufacturing", "marketCap": 3200000000000, "reportDate": "2026-05-01", "reportTime": "AMC", "fiscalQuarterEnding": "Jun/2026", "reported": false, "epsEstimate": 1.62, "epsActual": null, "epsSurprise": null, "numberOfAnalysts": 38, "previousEpsActual": 1.55, "epsGrowthYoY": 4.5 } ``` | Field | Type | Description | |-------|------|-------------| | `ticker` | string | Stock ticker symbol | | `companyName` | string | Full company name | | `sector` | string/null | Sector (Technology, Finance, Health Care, Industrials, etc.) | | `industry` | string/null | Industry within sector | | `marketCap` | number/null | Market capitalization in USD | | `reportDate` | string | Earnings report date (YYYY-MM-DD) | | `reportTime` | string | BMO (before market open), AMC (after market close), TBD | | `fiscalQuarterEnding` | string/null | Month/year the fiscal quarter ends (e.g., "Mar/2026") | | `reported` | boolean | Whether actuals have been released | | `epsEstimate` | number/null | Consensus EPS estimate | | `epsActual` | number/null | Actual reported EPS | | `epsSurprise` | number/null | EPS surprise percentage (positive = beat) | | `numberOfAnalysts` | integer/null | Analysts contributing to consensus | | `previousEpsActual` | number/null | Year-ago quarter actual EPS (upcoming earnings only) | | `epsGrowthYoY` | number/null | Year-over-year EPS growth % (upcoming earnings only) | All data is fetched live on every run. There is no caching. Estimates, actuals, and report dates always reflect the latest available data at the time of execution. ### **Use cases for earnings calendar data** | Use Case | Example Query | Who Uses It | |----------|---------------|-------------| | **Morning earnings scan** | "What reports this week?" (default settings) | Traders, portfolio managers | | **Post-earnings surprise scan** | Last 3 days, market cap > $500M, sort by epsSurprise | Momentum traders, newsletter writers | | **Pre-trade earnings gate** | Next 14 days, filter by watchlist tickers | Swing traders, risk managers | | **Sector sweep** | Next 30 days, sector = Energy | Sector analysts, event-driven traders | | **Portfolio risk check** | Next 7 days, filter by held tickers | Portfolio managers, robo-advisors | | **Earnings trend analysis** | 90 days back, specific ticker, check YoY growth | Fundamental analysts | | **Automated alerting** | Schedule daily, filter surprise > 10% | Trading systems, data pipelines | | **AI agent research** | Date range + sector filter via MCP | Claude, ChatGPT, custom agents | ### **How to get earnings data with Python** ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_TOKEN") run = client.actor("michael_b/stock-earnings-calendar").call(run_input={ "dateFrom": "2026-04-07", "dateTo": "2026-04-18", "marketCapMin": 1000, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): status = "BEAT" if (item.get("epsSurprise") or 0) > 0 else "MISS" if item.get("reported") else "UPCOMING" print(f"[{item['ticker']}] {item['reportDate']} {item['reportTime']} - {status} - EPS est: {item['epsEstimate']}") ``` ### **How to get earnings data with JavaScript** ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' }); const run = await client.actor('michael_b/stock-earnings-calendar').call({ dateFrom: '2026-04-07', dateTo: '2026-04-18', marketCapMin: 1000, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach(item => { const status = item.epsSurprise > 0 ? 'BEAT' : item.reported ? 'MISS' : 'UPCOMING'; console.log(`[${item.ticker}] ${item.reportDate} ${item.reportTime} - ${status}`); }); ``` ### **How to use with AI agents (MCP)** Connect this actor to any MCP-compatible AI agent: ```bash npx @apify/actors-mcp-server --actors michael_b/stock-earnings-calendar ``` Your AI agent can then query earnings data conversationally: - *"What stocks report earnings this week with market cap over $1B?"* - *"Did any tech stocks beat earnings estimates by more than 10% yesterday?"* - *"When does NVDA report next quarter?"* Works with Claude Desktop, ChatGPT with MCP plugins, and custom AI agents. ### **How much does it cost?** This actor uses pay-per-result pricing at $0.50 per 1,000 results. No browser overhead, recommended memory: **256 MB**. | Scenario | Records | Time | Est. Cost | |----------|---------|------|-----------| | Default (3 days back + 14 days forward) | ~500 | ~20s | ~$0.25 | | This week only (5 days) | ~30-100 | ~5s | ~$0.02-0.05 | | Next 30 days | ~2,000-3,000 | ~60-80s | ~$1.00-1.50 | | Specific tickers, 7 days | ~5-20 | ~5s | ~$0.01 | | Next 90 days, $1B+ market cap | ~2,000-2,500 | ~60s | ~$1.00-1.25 | ### **Automate with Apify platform** - **Schedule daily runs** at 6 AM ET before market open for automated morning scans - **Access results via API** and integrate into trading systems or dashboards - **Connect to Make, n8n, or Zapier** for no-code workflows and alerts - **Use with AI agents** through Apify's MCP server (Claude, ChatGPT, custom agents) - **Export** as JSON, CSV, Excel, or stream directly to your database - **Set up webhooks** to trigger downstream actions when new data is available ### **FAQ** **How far back and forward can I query?** Up to 365 days in either direction. The default range (3 days back, 14 days forward) covers the most common workflows: checking recent surprises and planning for upcoming reports. **What does `previousEpsActual` represent?** The year-ago quarter's actual EPS, available for upcoming earnings only (`reported: false`). For example, if a company is reporting Q2 2026, this shows Q2 2025's actual EPS. The `epsGrowthYoY` field uses this to compute year-over-year growth. Both fields are null for already-reported earnings. **What does `reported: false` mean?** The company hasn't released earnings yet. `epsEstimate` shows what analysts expect, but `epsActual`, `epsSurprise`, and related fields will be null. Once the company reports, these fields populate automatically on the next run. **How fresh is the data?** Live data fetched on every run, no caching. Estimates, actuals, and report dates always reflect the latest available data at the time of execution. For maximum freshness during earnings season, schedule hourly runs. **Are small and mid-cap stocks covered?** Yes. Coverage includes all US exchanges (NYSE, NASDAQ, AMEX) regardless of market cap. Use the `marketCapMin` filter to exclude smaller companies if needed. **Can I filter for earnings surprises?** Yes. Query a backward date range (e.g., last 7 days) and filter the results by `epsSurprise` value. Records with `reported: true` will have the surprise percentage populated. Use this for post-earnings momentum scans. **What do the `reportTime` values mean?** BMO = Before Market Open (typically 6-8 AM ET). AMC = After Market Close (typically 4-5 PM ET). TBD = timing not yet confirmed by the company. **Can I use this for non-US stocks?** Currently US exchanges only (NYSE, NASDAQ, AMEX). International coverage is planned for a future version. ### **Support** Questions, feature requests, or bugs? Open an issue in the [Issues tab](https://apify.com/michael_b/stock-earnings-calendar/issues). Feedback is welcome. # Actor input Schema ## `dateFrom` (type: `string`): Start of date range. Leave empty to default to 3 days ago. Supports up to 365 days back for historical surprise analysis. ## `dateTo` (type: `string`): End of date range. Leave empty to default to 14 days ahead. Supports up to 365 days forward for planning. ## `tickers` (type: `string`): Optional. Comma-separated ticker symbols to filter (e.g., AAPL, TSLA, MSFT). Leave empty for all stocks in the date range. ## `marketCapMin` (type: `integer`): Only include companies with market cap above this value in millions USD. E.g., 500 = $500M+, 2000 = $2B+. Set to 0 for no filter. ## `sector` (type: `string`): Optional. Filter results to a specific sector. ## Actor input object example ```json { "marketCapMin": 0, "sector": "" } ``` # Actor output Schema ## `results` (type: `string`): Dataset of earnings events with report dates, EPS estimates and actuals, surprise percentages, previous year comparisons, YoY growth, and sector classification. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "dateFrom": "", "dateTo": "", "tickers": "" }; // Run the Actor and wait for it to finish const run = await client.actor("michael_b/stock-earnings-calendar").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "dateFrom": "", "dateTo": "", "tickers": "", } # Run the Actor and wait for it to finish run = client.actor("michael_b/stock-earnings-calendar").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "dateFrom": "", "dateTo": "", "tickers": "" }' | apify call michael_b/stock-earnings-calendar --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=michael_b/stock-earnings-calendar", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Stock Earnings Calendar - Estimates, Actuals & Surprises", "description": "Get upcoming and recent US stock earnings by date range. Returns EPS estimates, actuals, surprise percentages, YoY growth, sector, and market cap. Filter by tickers, market cap, or sector. Export as JSON, CSV, or Excel. Flat schema for trading systems, dashboards, and AI agents via MCP.", "version": "0.1", "x-build-id": "AMQpUmOh2etZVjT35" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/michael_b~stock-earnings-calendar/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-michael_b-stock-earnings-calendar", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/michael_b~stock-earnings-calendar/runs": { "post": { "operationId": "runs-sync-michael_b-stock-earnings-calendar", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/michael_b~stock-earnings-calendar/run-sync": { "post": { "operationId": "run-sync-michael_b-stock-earnings-calendar", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "dateFrom": { "title": "Date From", "type": "string", "description": "Start of date range. Leave empty to default to 3 days ago. Supports up to 365 days back for historical surprise analysis." }, "dateTo": { "title": "Date To", "type": "string", "description": "End of date range. Leave empty to default to 14 days ahead. Supports up to 365 days forward for planning." }, "tickers": { "title": "Ticker Symbols", "type": "string", "description": "Optional. Comma-separated ticker symbols to filter (e.g., AAPL, TSLA, MSFT). Leave empty for all stocks in the date range." }, "marketCapMin": { "title": "Minimum Market Cap (Millions USD)", "minimum": 0, "type": "integer", "description": "Only include companies with market cap above this value in millions USD. E.g., 500 = $500M+, 2000 = $2B+. Set to 0 for no filter.", "default": 0 }, "sector": { "title": "Sector Filter", "enum": [ "", "Basic Materials", "Consumer Discretionary", "Consumer Staples", "Energy", "Finance", "Health Care", "Industrials", "Miscellaneous", "Real Estate", "Technology", "Telecommunications", "Utilities" ], "type": "string", "description": "Optional. Filter results to a specific sector.", "default": "" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```