# Quarterly Earnings Monitor (`trovevault/quarterly-earnings-monitor`) Actor Track quarterly revenue, EPS, margin, cash flow, and trend signals for public company tickers. - **URL**: https://apify.com/trovevault/quarterly-earnings-monitor.md - **Developed by:** [Trove Vault](https://apify.com/trovevault) (community) - **Categories:** Jobs, News, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $0.85 / 1,000 quarters This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ## Quarterly Earnings Monitor Quarterly Earnings Monitor turns public-company ticker lists into clean quarterly earnings rows with revenue, net income, diluted EPS, gross margin, operating cash flow, and trend signals. It is built for recurring watchlist monitoring during earnings season: one row per company per fiscal quarter, with simple options for latest quarter through long quarterly history. The actor focuses on quarterly filings for public companies covered by SEC EDGAR XBRL data. It does not ask users to choose sources or parser settings; you provide tickers and a quarter range, and the actor returns normalized metrics plus buyer-facing signals. ### Why use this actor - Track quarterly earnings across a watchlist without building SEC XBRL plumbing. - Compare recent quarters using YoY and QoQ revenue movement. - Spot acceleration, declines, margin pressure, net losses, and cash-flow issues. - Feed investor research, newsletters, corp dev screening, sales intelligence, or internal dashboards. - Run the same watchlist every earnings season and append the rows to your own dataset. ### What it returns Each dataset row represents one ticker and one fiscal quarter. The actor returns: - company and fiscal quarter identifiers - filing and period-end dates - revenue, net income, diluted EPS, gross profit, gross margin, operating income, and operating cash flow when available - revenue QoQ and YoY percentages - net income and EPS YoY percentages - `quarterSignalScore` from 0 to 100 - `growthSignal`, `profitabilitySignal`, and `cashSignal` The dataset intentionally avoids exposing internal source URLs, raw XBRL tags, source IDs, or debug telemetry. Operational details stay in `RUN_SUMMARY`. ### Use cases **Investor watchlists:** monitor 20-50 tickers every quarter and export a normalized table for screening, charting, or commentary. **Financial newsletters:** prepare earnings-season tables with recent quarterly trends that point editors toward companies worth writing about. **Sales intelligence:** watch target accounts for growth acceleration, revenue declines, cash pressure, or profitability changes before enterprise sales outreach. **Corp dev and competitive tracking:** compare public competitors across the same fiscal-quarter row shape without manually downloading filings. ### Input The actor has two core inputs: ```json { "tickers": ["AAPL", "MSFT", "NVDA"], "period": "last_4_quarters" } ```` #### `tickers` Array of public company ticker symbols, for example `AAPL`, `MSFT`, `NVDA`, `AMZN`, or `TSLA`. The actor resolves tickers to SEC company identifiers internally. #### `period` How many recent fiscal quarters to return for each ticker: - `latest_quarter` - `last_2_quarters` - `last_4_quarters` - `last_8_quarters` - `last_12_quarters` - `last_20_quarters` - `last_40_quarters` All options are quarterly. The actor does not switch to annual rows for longer periods. #### Optional pipeline fields `datasetId` appends the same rows to a dataset you provide. `runId` is copied into output rows so you can join the results with your own workflow metadata. ### Output example ```json { "ticker": "AAPL", "companyName": "Apple Inc.", "fiscalYear": 2026, "fiscalPeriod": "Q2", "periodEndDate": "2026-03-28", "filingDate": "2026-05-01", "form": "10-Q", "revenue": 95359000000, "revenueQoQPercent": 2.3, "revenueYoYPercent": 5.1, "netIncome": 24780000000, "netIncomeYoYPercent": 4.8, "dilutedEps": 1.57, "epsYoYPercent": 7.5, "grossProfit": 44400000000, "grossMarginPercent": 46.56, "operatingIncome": 29500000000, "operatingCashFlow": 28500000000, "quarterSignalScore": 82, "growthSignal": "accelerating", "profitabilitySignal": "stable", "cashSignal": "strong" } ``` ### API usage Start a run: ```bash curl -X POST "https://api.apify.com/v2/acts/trovevault~quarterly-earnings-monitor/runs" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIFY_TOKEN" \ -d '{ "tickers": ["AAPL", "MSFT", "NVDA"], "period": "last_4_quarters" }' ``` Fetch dataset items after the run finishes: ```bash curl "https://api.apify.com/v2/datasets/DATASET_ID/items" \ -H "Authorization: Bearer $APIFY_TOKEN" ``` ### How the signals work The score is a compact directional signal, not investment advice. It weighs revenue growth, sequential revenue pressure, gross-margin movement, net income, and operating cash flow when those fields are available. `cashSignal` is `null` when quarterly operating cash flow is not reported or cannot be derived from comparable year-to-date filings. Missing values are left as `null` when a company does not report a comparable quarterly fact. The actor avoids fabricating metrics from unsupported fields. ### Limitations - Coverage is strongest for public companies with SEC EDGAR XBRL filings. - This actor is quarterly-only. Longer ranges return more quarterly rows, not annual summaries. - Some companies use reporting concepts that do not map cleanly to every metric. Those fields may be `null`. - Q4 revenue, net income, gross profit, operating income, and operating cash flow may be derived from full-year filings when Q1-Q3 comparable quarterly values are available. Diluted EPS is not derived this way. - The actor does not include analyst estimates, earnings surprise, transcripts, guidance, or non-GAAP adjustments. - The output is for research and monitoring workflows, not financial advice. ### Troubleshooting **Ticker returns no rows:** check that the ticker appears in SEC company ticker data and has recent XBRL filings. **Some metrics are null:** the company may not report that concept in a comparable quarterly XBRL fact, or the metric may use a company-specific extension that is not normalized yet. **Long periods return fewer rows than requested:** the company may have less quarterly history available in comparable XBRL facts. **Rows appear after a filing delay:** public filings can arrive and be processed at different times during earnings season. Re-run the actor later if a very recent filing is not yet reflected. ### FAQ **Does this work for non-US companies?**\ Only when the company is covered by SEC EDGAR XBRL filings in a way the actor can normalize. The first version is intentionally SEC-first. **Can I request custom date ranges?**\ Not in the MVP. Use the predefined quarterly ranges so Store runs stay predictable and comparable. **Does it expose the raw source link?**\ No. The public dataset focuses on the normalized decision layer. Run diagnostics are stored in `RUN_SUMMARY`. **Can I use this with MCP or downstream agents?**\ Yes. Run it on a schedule, fetch the dataset through the Apify API, or pass rows into your own MCP-enabled research workflow. ### Related actors Use this actor alongside watchlist, market-intelligence, CRM enrichment, and reporting workflows when quarterly financial movement should influence prioritization. ### Changelog #### 0.1 - Initial quarterly-only SEC EDGAR XBRL implementation. - Supports latest quarter through last 40 quarters. - Adds revenue, EPS, margin, cash-flow, trend, and score fields. ### Feedback and support Open an issue on the actor page with example tickers and the quarter range you used. Include what field looked missing or surprising so the normalization can be improved with a concrete case. # Actor input Schema ## `tickers` (type: `array`): Public company ticker symbols to monitor. Use common US exchange tickers such as AAPL, MSFT, NVDA, AMZN, or TSLA. ## `period` (type: `string`): How many recent fiscal quarters to return for each ticker. Longer ranges are useful for trend analysis but produce more rows. ## `datasetId` (type: `string`): Optional Apify dataset ID. When supplied, the actor appends the same rows to that dataset for pipeline workflows. ## `runId` (type: `string`): Optional ID copied into output rows so you can join this run with your own workflow metadata. ## Actor input object example ```json { "tickers": [ "AAPL", "MSFT", "NVDA" ], "period": "last_4_quarters" } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `summary` (type: `string`): No description ## `runSummary` (type: `string`): No description # 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 = { "tickers": [ "AAPL", "MSFT", "NVDA" ] }; // Run the Actor and wait for it to finish const run = await client.actor("trovevault/quarterly-earnings-monitor").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 = { "tickers": [ "AAPL", "MSFT", "NVDA", ] } # Run the Actor and wait for it to finish run = client.actor("trovevault/quarterly-earnings-monitor").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 '{ "tickers": [ "AAPL", "MSFT", "NVDA" ] }' | apify call trovevault/quarterly-earnings-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=trovevault/quarterly-earnings-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Quarterly Earnings Monitor", "description": "Track quarterly revenue, EPS, margin, cash flow, and trend signals for public company tickers.", "version": "0.1", "x-build-id": "yWuONFqPca9Wh0ozl" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/trovevault~quarterly-earnings-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-trovevault-quarterly-earnings-monitor", "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/trovevault~quarterly-earnings-monitor/runs": { "post": { "operationId": "runs-sync-trovevault-quarterly-earnings-monitor", "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/trovevault~quarterly-earnings-monitor/run-sync": { "post": { "operationId": "run-sync-trovevault-quarterly-earnings-monitor", "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", "required": [ "tickers", "period" ], "properties": { "tickers": { "title": "Ticker symbols", "minItems": 1, "maxItems": 50, "type": "array", "description": "Public company ticker symbols to monitor. Use common US exchange tickers such as AAPL, MSFT, NVDA, AMZN, or TSLA.", "items": { "type": "string" } }, "period": { "title": "Quarter range", "enum": [ "latest_quarter", "last_2_quarters", "last_4_quarters", "last_8_quarters", "last_12_quarters", "last_20_quarters", "last_40_quarters" ], "type": "string", "description": "How many recent fiscal quarters to return for each ticker. Longer ranges are useful for trend analysis but produce more rows.", "default": "last_4_quarters" }, "datasetId": { "title": "Append to dataset", "type": "string", "description": "Optional Apify dataset ID. When supplied, the actor appends the same rows to that dataset for pipeline workflows." }, "runId": { "title": "Pipeline run ID", "type": "string", "description": "Optional ID copied into output rows so you can join this run with your own workflow metadata." } } }, "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 } } } } } } } } } } ```