Actor Monitoring — Usage Reports & Run Comparison

Track cost, reliability, and output volume across every Apify Actor and Task in your account — without building dashboards or writing glue code. Point it at your account, pick a mode, and it collects the runs, crunches the numbers, and delivers a polished email digest plus an Excel workbook and a self-contained HTML dashboard saved to storage.

It runs in three modes:

• Monthly usage report — an Excel workbook, a self-contained HTML dashboard, and an email digest covering runs, cost, success rate, and product volume across your account over the last N calendar months, with month-over-month trends.
• Weekly usage report — the same workbook, dashboard, and digest over the last N calendar weeks (Monday–Sunday), with week-over-week trends. Schedule it weekly in Apify.
• Run comparison — checks the latest run of each monitored Actor/Task against a baseline (previous run, pinned run, or historical average) and emails an alert when items, runtime, cost, or specific dataset fields change.

All modes share the same run collection, filtering, and email delivery, so one configuration covers ongoing usage reporting and regression alerting.

Quick start

Monthly report — three fields, everything else has a working default:

{
    "actorMode": "monthly",
    "emailRecipients": ["you@example.com"],
    "actorNameInclude": ["my-scraper"]
}

Weekly report — same fields, weekly mode; reports on the last 4 calendar weeks by default:

{
    "actorMode": "weekly",
    "emailRecipients": ["you@example.com"],
    "actorNameInclude": ["my-scraper"]
}

Run comparison — same three fields, different mode. Defaults to comparing the last two SUCCEEDED runs of each matching Actor/Task:

{
    "actorMode": "compare",
    "emailRecipients": ["you@example.com"],
    "actorNameInclude": ["my-scraper"]
}

Leave emailRecipients empty to skip email — every artifact is still written to the key-value store and dataset.

Input reference

Fields are grouped into form sections in this order; a monthly or weekly user never needs to scroll past section 4, a compare user never needs section 4 at all.

1. Get started

Field	Type	Default	Description
actorMode	string (monthly | weekly | compare)	monthly	Which report to build.
emailRecipients	array of strings	[]	Who receives the email. Empty = no email, artifacts still saved.
actorNameInclude	array of strings	[] (all actors)	Only monitor Actors whose name contains one of these substrings.

2. Actor & task scope

Field	Type	Default	Description
useDirectActorRuns	boolean	false	Collect runs directly per Actor instead of via saved Tasks.
actorNameExclude	array of strings	[]	Skip Actors matching these substrings.
actorNamePattern	string (regex)	unset	Replaces the include/exclude substring lists when set.
taskNameInclude	array of strings	[] (all tasks)	Only monitor Tasks matching these substrings. Ignored when useDirectActorRuns is on.
taskNameExclude	array of strings	[]	Skip Tasks matching these substrings. Ignored when useDirectActorRuns is on.
taskNamePattern	string (regex)	unset	Replaces the Task include/exclude lists when set. Ignored when useDirectActorRuns is on.
actorIds	array of strings	unset	Explicit Actor IDs; skips name-based discovery.
filterRunsByStatus	array (SUCCEEDED/FAILED/ABORTED/RUNNING/TIMED-OUT)	all statuses in monthly/weekly, SUCCEEDED only in compare	Only collect runs with these statuses.
runInputFilters	array of objects	unset	Include/exclude runs by their input values, e.g. {"field": "country", "operator": "equals", "value": "US", "action": "include"}. Operators: equals, notEquals, exists, notExists, in, notIn, contains. Max 20 rules. Explicitly compared run IDs are never filtered out.
runInputFilterMode	string (all | any)	all	How multiple include rules combine; exclude rules always drop a run on match.

3. Email & delivery

Field	Type	Default	Description
outputMode	string (email | dataset | both)	email	Where results go. dataset skips email even with recipients set; storage artifacts are always saved.
emailSubject	string	mode-appropriate default	Template with {mode}, {date}, {actorCount}, {status} placeholders.
emailSections	object	all true	Toggle sections: showCostBreakdown, showRunLinks (both modes); showSchemaChanges, showTrendAnalysis, showAnomalyDetection, showBuildChanges, showFieldDiscovery (compare only).
emailFooterText	string	unset	Custom line appended to the email footer.
dryRun	boolean	false	Build everything but send no email — the rendered HTML is saved to the key-value store as dry-run-email-preview.html.

4. Monthly / weekly report

Applies to actorMode: monthly or weekly only — ignored in compare mode. Use monthsToAnalyze/includeCurrentMonth in monthly mode and weeksToAnalyze/includeCurrentWeek in weekly mode; the rest apply to both.

Field	Type	Default	Description
monthsToAnalyze	integer (1–24)	3	(Monthly) Calendar months of runs to report on. Ignored when a custom date range is set.
includeCurrentMonth	boolean	true	(Monthly) Whether the (partial) current month counts as one of the analyzed months.
weeksToAnalyze	integer (1–52)	4	(Weekly) Calendar weeks (Monday–Sunday) of runs to report on. Ignored when a custom date range is set.
includeCurrentWeek	boolean	true	(Weekly) Whether the (partial) current week counts as one of the analyzed weeks.
dateRangeStart	string (YYYY-MM-DD)	unset	Custom period start; overrides monthsToAnalyze/weeksToAnalyze when both dates are set.
dateRangeEnd	string (YYYY-MM-DD)	today	Custom period end, inclusive.
topNActors	integer (1–20)	5	Rows in each dashboard ranking (top cost, top failing, health).
customDimensions	array of objects	group by calendar month (monthly) or ISO week (weekly)	Group the report by run fields instead of by reporting period. Up to 5 dimensions; see docs/field-comparison.md for recipes.
enableAggregation	boolean	true	Adds the Aggregated Insights view: item volume per product dimension with period-over-period growth and yield alerts.
saveHtmlDashboard	boolean	true	Saves the standalone HTML dashboard to the key-value store and links it from the email.
healthScoreWeights	object	{successRate: 0.47, zeroItemInverse: 0.29, costEfficiency: 0.24}	Weights of the 0–100 actor health score; must sum to 1.0.

5. Compare runs

Applies to actorMode: compare only — ignored in monthly and weekly modes.

Field	Type	Default	Description
compareMode	string (last2 | lastVsBaseline | lastVsAverage)	last2	How the baseline is chosen. lastVsBaseline needs baselineRunId; lastVsAverage averages baselineRunCount runs. Ignored when explicit run IDs are set.
baselineRunId	string	unset	Pinned known-good run. Required for lastVsBaseline.
baselineRunCount	integer (2–20)	5	Historical runs averaged for lastVsAverage.
compareRunId1	string	unset	Explicit baseline run ID. Takes full precedence over compareMode/baselineRunId when set together with compareRunId2.
compareRunId2	string	unset	Explicit "current" run ID for a two-run comparison.
maxDatasetItems	integer (100–10000)	1000	Dataset items fetched per run for field-level comparison.
enableCompareExcel	boolean	false	Saves a comparison workbook (compare-report.xlsx) to the key-value store.
combineEmails	boolean	true	Send one consolidated email for all compared entities instead of one per entity. Monthly and weekly modes always send a single email.

6. Compare — field rules

Applies to actorMode: compare only.

Field	Type	Default	Description
fieldsAndCompareStrategy	object	discovery mode	Which dataset fields to compare and how, e.g. {"results.price": "average", "items": {"strategy": "count", "lowerIsBetter": false}}. Use [] to reach into arrays of objects (reviews[].rating). 25 strategies available — see docs/field-comparison.md. Omitting this field, or passing {}, runs field discovery instead of comparison.
excludeFields	array of strings	[]	Field paths to skip — from comparison when strategies are configured, from the discovery report otherwise.

7. Compare — trends & anomalies

Applies to actorMode: compare only; both features need at least 3 runs of history.

Field	Type	Default	Description
enableTrendAnalysis	boolean	false	Linear-regression trend analysis (items/runtime/cost) over recent runs.
trendRunCount	integer (3–50)	10	Recent runs feeding trend analysis.
enableAnomalyDetection	boolean	false	Z-score anomaly flagging. Works independently of trend analysis.
anomalyStdDevMultiplier	number (1–5)	2	Standard-deviation multiplier — lower is more sensitive.

8. Alerts & notifications

Field	Type	Default	Description
alerts	object	{changePercent: 5, yieldDropPercent: 20}	One place for every "how big a change matters" setting: changePercent (compare-mode email gate), itemsCount/runtimeSecs/costUsd (percent-change severity bands for compare), avgRuntimeSecs/avgCostUsd (absolute monthly Threshold Breaches in seconds/USD), custom (per-field bands; also failureRate/zeroItemRate for monthly), yieldDropPercent (aggregation yield alert).
notifyOnSignificantChange	boolean	true	Compare mode: only email when at least one metric changed by alerts.changePercent or more.
alwaysSendSummary	boolean	false	Compare mode: send an "all clear" summary email even when nothing significant changed.

9. Billing

Field	Type	Default	Description
pricePerItem	number	unset (billing hidden)	Your client-facing USD price per dataset item. Adds Billed and Margin columns (billed = items × price, margin = billed − Apify cost) to both modes.

10. Limits & advanced

Field	Type	Default	Description
maxRuns	integer (1–50000)	100	Cap on runs fetched per monitored Actor/Task.
concurrencyLimit	integer (1–20)	5	Actors/Tasks collected in parallel.
circuitBreakerThreshold	integer (1–50)	3	Abort the run once at least this many actors/tasks fail to collect and at least half of the processed items have failed. If the first few processed items all fail (e.g. an invalid token), the run aborts immediately.
token	string (secret)	account running the Actor	API token of the account to monitor.
debug	boolean	false	Verbose logs for troubleshooting.

Output reference

Artifact	What it is	Where it lands
Excel workbook (monthly/weekly)	Multi-sheet report: Contents, Executive Dashboard, Entity Metrics, Category Summary, All Runs, Aggregated Insights, Threshold Breaches, Cost Breakdown	Key-value store, key {base}-sheet.xlsx
Comparison workbook (compare)	Summary + field-detail + inventory sheets for the compared entities	Key-value store, stable key compare-report.xlsx (when enableCompareExcel is on)
HTML dashboard (monthly/weekly)	Standalone, self-contained HTML page — KPI tiles, trend charts, rankings, health board, no external requests	Key-value store, key {base}-dashboard.html (when saveHtmlDashboard is on)
Categorized run export	Slim JSON of every collected run (id, names, dates, status, items, runtime, cost, build)	Key-value store, key {base}.json
Report manifest	Links every report artifact together with public URLs	Key-value store, key {base}-manifest.json
Compare manifest	Run counts, comparison/skip counts, and the compare Excel key (compare mode)	Key-value store, key compare-manifest.v2
last-report-summary	Structured JSON snapshot of the latest run, for the Output tab and downstream automation	Key-value store, key last-report-summary
Diff lineage	Per-cadence snapshot the next same-cadence run diffs against for the period-over-period comparison	Key-value store, key report-diff-lineage-{week|month|date-range}
Field discovery report	Per-entity auto-discovered field types and suggested strategies, when no fieldsAndCompareStrategy is configured	Key-value store, key field-discovery-report.v2.{entity}
Dataset records	comparison.v4 rows (compare mode, one per field/run comparison) or monthly-report.v4 rows (monthly/weekly mode, one per report) plus processing-failures.v2 on per-item errors	Default dataset — Console has Overview, Comparisons, and Usage Reports views
Email	HTML digest sharing the same computed metrics as the Excel/HTML dashboard (monthly/weekly KPI parity). Trend summary labels total-runtime PoP separately from the avg-runtime table column; compare-mode request % is Crawlee-only when request stats are mixed	Sent via apify/send-mail when outputMode includes email and recipients are set

Metric definitions (monthly / weekly / date-range)

Metric	Definition
Success rate	SUCCEEDED / terminal runs where terminal = SUCCEEDED | FAILED | ABORTED | TIMED-OUT. In-flight statuses (RUNNING, READY, ABORTING, TIMING-OUT) are excluded from the denominator.
Zero-item success share (zeroItemSuccessRate)	Share of succeeded runs that produced zero items — not “success rate among zero-item runs.”
Period-over-period headlines	Calendar MoM/WoW for week/month (last two buckets). Custom date-range windows use a mid-window half-split aligned with Aggregated Insights.
Email {status} / subject alert emoji	Driven by reliability signals (failures, zero-item successes, or no terminal successes) — not by cost watchlist tips alone.
weekNumber transform	ISO week label with year prefix, e.g. 2026-W30.

Invalid emailRecipients entries produce validation warnings and are skipped at send time; they do not abort the Actor.

The Console's Run tab (Output section) also surfaces one-click links via .actor/output_schema.json: the last-report-summary record (whose artifacts field carries this run's actual Excel/dashboard/manifest URLs — report artifact keys vary with the reporting period, so they can't be linked directly), the dataset items, and — in compare mode — the compare manifest and comparison workbook.

Data & privacy

This Actor reads data from the runs it monitors and embeds values from it into its outputs. There is no redaction layer — treat every artifact and email as potentially containing third-party PII:

• Compare mode embeds actual dataset field values (the ones you compare) into the comparison workbook, dataset records, and alert emails. If a monitored dataset holds personal data (emails, names, addresses, scraped user content), those values appear verbatim in the outputs.
• runInputFilters match against monitored runs' input values, which can themselves contain personal or sensitive data (search terms, targeted URLs, credentials embedded in inputs).

Because outputs can carry this data, restrict accordingly: limit emailRecipients to people cleared to see the monitored data, and control who can access this Actor's key-value store and default dataset. Prefer non-sensitive fields for comparison where possible.

FAQ

Does this send Slack/webhook notifications? No. Use Apify Console's built-in run webhooks on this Actor/Task for that.

Why did my field comparison show no results? Check fieldsAndCompareStrategy isn't an empty object {} — that's treated the same as omitting it, which runs field discovery (suggestions only) instead of comparison. See docs/field-comparison.md.

Can I compare two arbitrary runs? Yes — set compareRunId1 and compareRunId2; they take full precedence over compareMode and baselineRunId.

Where do I find real, working example configs? See examples/ and examples/README.md.

Local development

npm install
npm test

Example configs live in examples/. Field-comparison recipes are in docs/field-comparison.md.