# Earnings Guidance Change Monitor - SEC Ranges (`maydit/earnings-guidance-change-monitor`) Actor

Extract explicit EPS, revenue and margin guidance ranges from SEC earnings exhibits. Compare matching fiscal periods with evidence, prior ranges and review flags. No API key.

- **URL**: https://apify.com/maydit/earnings-guidance-change-monitor.md
- **Developed by:** [Brandt May](https://apify.com/maydit) (community)
- **Categories:** Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 guidance observations

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

![Earnings guidance ranges, period comparisons and SEC evidence](https://api.apify.com/v2/key-value-stores/nemaYfVcrTgloz8Wn/records/earnings-guidance-change-monitor-2661a5cd82b2.png?signature=DB9YLlJqJJaJtLuUisEL)

### See what changed in company guidance

Turn explicit EPS, revenue and margin guidance from SEC earnings exhibits into a research table. Keep each range attached to its fiscal period, accounting basis and original evidence, then compare matching observations over time.

Use it to review earnings releases, maintain a company watchlist or feed a research workflow. **No API key or proxy is required.**

[Open Actor](https://console.apify.com/actors/SN5SF660xLICDOkFr/input) · [Read the results](#read-the-results) · [Saved monitoring](#build-a-saved-guidance-watchlist) · [Coverage and reference](#coverage-and-reference)

### Try one earnings exhibit

Start with this fixed Walmart FY2027 Q2 exhibit to see how a single document becomes inspectable guidance rows.

1. Open the Actor and select the **JSON** input editor.
2. Paste the input below and click **Start**.
3. Open the output table, review the fiscal period and range, then follow **SEC source** to the filing.

```json
{
  "documentUrls": [
    "https://www.sec.gov/Archives/edgar/data/104169/000010416926000145/earningsreleasefy27q2.htm"
  ],
  "maxResults": 10
}
```

Prefer a current sample? Click **Start** with the default input to inspect Walmart’s recent filings (CIK 104169). The fixed document above is a historical example; the default follows the SEC’s current recent-filings response.

### Read the results

| Your research question | Fields to inspect |
| --- | --- |
| Which company and period does this cover? | `companyName`, `tickers`, `targetPeriod` |
| What range did the company state? | `metric`, `low`, `high`, `unit` |
| Are these figures comparable? | `accountingBasis`, `currencyBasis` |
| Did guidance change between sources? | `guidanceChange` and the prior/current evidence |
| Can I use the extracted number directly? | `extractionConfidence`, review reasons and `quote` |
| Where did it come from, and when? | `sourceUrl`, `filingDate`, `acceptedAt`, `observedAt` |

**Compare the same period and basis.** A new quarter is not a guidance increase over the previous quarter. `guidanceChange` compares source guidance; `savedGuidanceChange` compares a matching observation against your saved history. These fields do not measure stock-price impact.

A statement that cannot be safely parsed keeps its evidence, null numeric bounds and `needs_review` status. A valid current range can also have a review reason when its prior value is not comparable.

#### Check coverage before using the export

Export the dataset as **JSON or CSV** from the run’s output panel. Each observation includes the original SEC URL, accession, filing date, acceptance timestamp when available, and observation time.

In the Output tab, open **Run report** for a readable coverage report or **Coverage and history summary** (`SUMMARY`) for machine-readable source coverage, unsupported cases, failures, saved rows and limits. Reports create no paid dataset rows. A successful run can have partial coverage; SUMMARY marks it explicitly.

### Usage and pricing

**$5 per 1,000 saved observations on the FREE plan** ($0.005 per observation), plus the applicable Actor Start charge. The [Pricing tab](https://apify.com/maydit/earnings-guidance-change-monitor/pricing) is authoritative for your plan and current charges.

One confirmed saved observation is one result. Failure messages and run reports are never charged as result rows. Set Apify’s spending limit and `maxResults` before scheduling. The Actor checks the remaining dataset-item charge allowance before writing.

### Build a saved guidance watchlist

#### Follow recent company filings

Collect current explicit guidance ranges from Walmart’s recent SEC earnings exhibits.

```json
{
  "ciks": [
    "104169"
  ],
  "maxFilingsPerCompany": 3,
  "maxResults": 10
}
```

Replace the sample CIK with your companies’ exact SEC identifiers. Current SEC ticker arrays are included for convenience; they are not historical ticker mappings.

#### Save a baseline, then follow changes

Save the current observations; later runs identify changed or unchanged source guidance.

```json
{
  "ciks": [
    "104169"
  ],
  "maxFilingsPerCompany": 2,
  "comparePrevious": true,
  "snapshotName": "wmt-guidance-research",
  "maxResults": 10
}
```

1. Run this input once to establish a baseline. First observations are marked new.
2. Save it as an Apify task and reuse the same watchlist, filing limit, date filter and history names.
3. On later runs, inspect the comparison fields. Enable **Save only new or changed observations** (`onlyChanges`) when you want an incremental output.
4. Schedule the saved task at a cadence suited to your research. An unchanged repeat can correctly produce zero rows.

Use a dedicated history name/store per workflow and allow only one run at a time for that scope.

### Coverage and reference

#### Supported guidance

The Actor looks inside explicitly headed Guidance/Outlook sections of selected HTML EX-99.1 exhibits furnished with recent 8-K filings and amendments under Items 2.02, 7.01 or 8.01. Only the first HTML EX-99.1 is inspected. It supports two-ended numeric ranges for EPS, revenue, revenue growth, gross margin, operating margin and EBITDA margin. A range’s fiscal year or quarter, accounting basis, currency basis and units stay attached to it. Revenue-growth percentages are distinct from currency revenue. Naked EPS ranges and unsupported currency labels are left for review. Dollar symbols without an explicit USD label are marked `dollar_unspecified`.

#### How source comparisons work

The same fiscal period, metric, accounting basis, currency basis and unit form one observation identity. When a table includes prior and current guidance columns, their labels and values are retained; an explicit “Unchanged” cell carries forward that row’s prior value. Otherwise the latest source may be compared with an older matching-period observation in the inspected filings. Unspecified accounting bases do not receive cross-document numeric comparisons. A new quarter is never treated as a guidance increase over the old quarter. `guidanceChange` describes source-to-source range changes; `savedGuidanceChange` describes a matching observation from your saved history. Neither measures stock-price impact.

#### Extraction limits

A quoted guidance statement that cannot be safely parsed has null numeric bounds, `extractionConfidence: needs_review` and explicit reasons. This version does not parse PDFs, charts, implied ranges, analyst consensus, withdrawal/reaffirmation announcements without a supported numeric statement, or every issuer layout. Missing supported guidance is reported as an empty source observation, not proof the company gave no guidance.

#### Inputs and saved-history boundaries

- `ciks`: up to 10 exact SEC company identifiers. The source checks company identity before parsing filings.
- `documentUrls`: up to 10 specific official SEC HTML documents, validated against their accession index. Direct documents suppress the sample fallback. Combine them with explicit CIKs when intentional.
- `maxFilingsPerCompany`: 1–10 matching filings from the SEC’s current recent-submissions response; default 3. Old archive pages are not scanned.
- `filedFrom`: optional inclusive filing-date filter. Historical direct documents with unavailable filing dates do not pass a date filter.
- `comparePrevious`: save and compare observations in your named key-value store. The first run is a new baseline.
- `onlyChanges`: implies comparison and suppresses unchanged observations. A repeat can correctly save zero rows.
- `snapshotName` / `stateStoreName`: isolate workflows. Scope includes the exact watchlist, document URLs, date filter and filing bound. Use one writer per scope; overlapping runs are unsupported.

Source chronology is checked using SEC acceptance timestamps when available, otherwise strictly ordered filing dates. A stale or temporally ambiguous replacement of saved guidance is skipped and counted in SUMMARY; it cannot overwrite newer guidance. Only confirmed saved dataset rows advance history. A source failure cannot erase previous observations. No disappearance or deletion is inferred from bounded or missing filings.

#### Source access and run limits

SEC requests are sequential with at least 1.1 seconds between request starts; every request has a deadline and an 8 MiB response cap. There are no paid providers, proxies, generative-model calls or credential requirements. SEC refusals and timeouts remain visible in SUMMARY. Coordinate parallel runs to respect the SEC’s aggregate fair-access policy.

#### Source and interpretation

Data comes from official [SEC submissions APIs](https://www.sec.gov/search-filings/edgar-application-programming-interfaces) and the [EDGAR archive](https://www.sec.gov/edgar/search/). See [SEC developer resources](https://www.sec.gov/about/developer-resources) for fair access. Filing acceptance time, disclosure/event date and observation time are different; this Actor does not promise real-time exchange data or a trading signal.

Questions about an extraction? Include the run ID, source URL and relevant excerpt when reporting it through the Actor’s Issues tab.

[Explore Maydit data tools](https://mayd-it.com/data-tools/) · [Quality dashboard](https://mayd-it.com/data-tools/quality/) · [Workflow recipes](https://mayd-it.com/data-tools/workflows/)

# Actor input Schema

## `ciks` (type: `array`):

Up to 10 SEC company CIKs (digits only). Omitted or empty uses Walmart (104169) unless direct documents are supplied. Company names and ticker arrays come from SEC submissions; no fuzzy ticker matching.

## `documentUrls` (type: `array`):

Up to 10 HTTPS www.sec.gov/Archives/edgar/data HTML URLs. Each must appear in its official accession index. Supplying documents suppresses the sample company fallback. Can be combined with explicit CIKs.

## `maxFilingsPerCompany` (type: `integer`):

Inspect up to this many recent 8-K / amendments reporting Items 2.02, 7.01 or 8.01; only the first EX-99.1 HTML exhibit is parsed. Some filings have no supported guidance.

## `filedFrom` (type: `string`):

Optional YYYY-MM-DD. Filters recent filings by SEC filing date. Does not load old submission archives; direct documents with an unknown filing date are excluded when this filter is set.

## `maxResults` (type: `integer`):

Maximum confirmed dataset rows. Skipped unchanged observations do not count. Source requests remain bounded separately by the watchlist and filing limit.

## `comparePrevious` (type: `boolean`):

First observations are new. Later observations are changed or unchanged; only confirmed saved rows can advance history.

## `onlyChanges` (type: `boolean`):

Implies comparePrevious. A fully unchanged run correctly saves zero rows. The initial comparison saves new observations.

## `snapshotName` (type: `string`):

1-80 letters, numbers, underscores or hyphens. History scope includes sorted CIKs/documents, filing bound and date filter. Use only one writer per namespace.

## `stateStoreName` (type: `string`):

3-63 letters, numbers or hyphens. Read/written only when comparisons are requested. Use your own dedicated store to isolate a workflow.

## `maxRunSeconds` (type: `integer`):

Includes source and history work, also bounded by the platform deadline minus 25 seconds.

## Actor input object example

```json
{
  "ciks": [
    "104169"
  ],
  "documentUrls": [],
  "maxFilingsPerCompany": 3,
  "maxResults": 10,
  "comparePrevious": false,
  "onlyChanges": false,
  "snapshotName": "default",
  "stateStoreName": "maydit-earnings-guidance-change",
  "maxRunSeconds": 240
}
```

# Actor output Schema

## `results` (type: `string`):

Source-backed extracted guidance or offering observations. Failures are never synthetic paid rows.

## `runReport` (type: `string`):

Readable coverage, limits and history outcome from this run.

## `summary` (type: `string`):

Source documents, unsupported cases, time/spending limits and saved-history status.

## `csvExport` (type: `string`):

Download the current run observations for spreadsheets.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "ciks": [
        "104169"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maydit/earnings-guidance-change-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "ciks": ["104169"] }

# Run the Actor and wait for it to finish
run = client.actor("maydit/earnings-guidance-change-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "ciks": [
    "104169"
  ]
}' |
apify call maydit/earnings-guidance-change-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,maydit/earnings-guidance-change-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SN5SF660xLICDOkFr/builds/eqhvRtiWomr0i4CKl/openapi.json