Health Monitor

Actor Health Monitor scans your entire Apify actor fleet in one run — diagnosing why each actor fails, whether failures are getting worse, and how much revenue each problem is costing you. Built for developers who manage more than a handful of actors and can't afford to discover breakage from user complaints.

Instead of clicking through individual run logs in the Apify Console, you get a structured health report across every actor in your account: failure categories, trend direction, dollar impact, and specific fix recommendations — all in a single dataset you can pipe into Slack, Zapier, or your own dashboards.

What data can you extract?

A final fleet summary record is always appended, containing total actor count, overall failure rate, top issue category, and total estimated revenue impact across your portfolio.

Why use Actor Health Monitor?

Manual fleet monitoring means opening the Console, scanning run lists actor by actor, clicking into failed runs, reading raw logs, and trying to remember whether this was happening last week too. For a portfolio of 20+ actors, that is an hour of work per incident — and it only happens after something is already broken.

This actor automates the entire process. One run, one structured dataset, sorted by severity. You know which actors are on fire, exactly why they are failing, whether the situation is improving or deteriorating, and what the first fix action is.

• Scheduling — run daily, twice daily, or on any cron schedule to catch problems before users do
• API access — trigger from Python, JavaScript, or any HTTP client to integrate with your deployment pipeline
• Webhook alerting — POST structured JSON to Slack, Discord, Teams, Zapier, or n8n when failures exceed your threshold
• Monitoring — get Slack or email alerts when fleet failure rates spike above your defined quality bar
• Integrations — connect to Zapier, Make, PagerDuty, or any webhook-capable alerting system

Features

• 7-category failure diagnosis — Reads the last 500 characters of each failed run's log and classifies the root cause: timeout, schema_mismatch, credential_error, memory_exceeded, input_validation, api_down, or unknown
• Pattern-matched log analysis — Matches against specific error signatures: pushData, validation failed, ETIMEDOUT, 401, 403, ENOMEM, heap out of memory, ECONNREFUSED, socket hang up, and more
• Current vs. previous period trend comparison — Computes failure rates for both the current window and the prior window of equal length, then classifies each actor as improving, worsening, stable, or new_issue
• Revenue impact estimation — Multiplies failedRuns × avgResultsPerRun × pricePerResult using your actor's PAY_PER_EVENT pricing configuration; identifies primary charge events vs. secondary events
• Per-actor actionable recommendations — Generates specific fix suggestions for each failure category, including severity labels (CRITICAL at >50%, HIGH at >25%) and concrete action steps
• Public 30-day stats overlay — Pulls platform-wide run statistics to flag actors failing for other users even when your own account shows no failures
• Webhook alert payload — Sends a structured JSON summary to your endpoint including all actors over threshold, their top failure category, and recommendations
• Fleet summary record — Always outputs a summary with topIssue identifying the failure category affecting the most actors across your portfolio
• Paginated actor discovery — Iterates through all your actors in batches of 100, handling portfolios of any size
• Dual log endpoint fallback — Tries the direct /logs/{runId} endpoint first, then falls back to /acts/{actorId}/runs/{runId}/log for maximum log retrieval success
• Configurable failure threshold — Set to 0 to alert on any failure, or 0.5 to only surface actors with catastrophic failure rates
• Severity sorting — Output dataset sorted CRITICAL → WARNING → HEALTHY for immediate triage

Use cases for Apify actor health monitoring

Daily fleet monitoring

Developers managing 20-500 actors cannot manually check each one every day. Schedule Actor Health Monitor to run each morning and pipe results to a Slack channel. You start every day knowing exactly which actors degraded overnight — and why — before a single user reports an issue.

Post-deployment validation

After pushing code updates to any actor, trigger Actor Health Monitor with a short hoursBack window (e.g., 2-4 hours) to verify the deployment did not introduce regressions. Compare failure rates before and after the change by adjusting the window. This catches schema breaks and timeout regressions within minutes of a deploy.

Revenue protection for PPE actors

If you run pay-per-event actors, each failed run is direct lost revenue. Actor Health Monitor calculates the exact dollar impact per actor using your PPE pricing configuration and average output volume. Sort by estimatedRevenueLoss to prioritize the fixes with the highest financial return.

SLA and quality bar enforcement

Set failureThreshold to 0.05 (5%) and connect a webhook to PagerDuty, Opsgenie, or a Slack alert channel. Any actor that degrades below your quality bar triggers an immediate alert. This turns reactive debugging into proactive operations.

Multi-actor debugging and triage

When something breaks across a large portfolio, finding the affected actors is the first bottleneck. Actor Health Monitor surfaces all failures in one dataset, sorted by severity, with the failure category already diagnosed. A 30-minute debugging session becomes a 5-minute triage.

Public user failure detection

Some actors fail for end users on inputs you have never tested yourself. The public 30-day stats overlay catches actors where external users are experiencing failures even when your own test runs are clean — a class of problem invisible in standard monitoring.

How to monitor your Apify actor fleet

1. Provide your API token — Enter your Apify API token from console.apify.com/account/integrations. This is used to fetch your actors and their run logs.
2. Set the time window — The default hoursBack: 24 checks the last 24 hours. Use 168 for a full week review, or 4 for a post-deployment quick check.
3. Run the actor — Click "Start" and wait 1-3 minutes. Larger portfolios (200+ actors) take longer; most runs complete under 5 minutes.
4. Review results — Open the Dataset tab. Records are sorted by severity: CRITICAL actors appear first. The last record is always your fleet summary.

Input parameters

Input examples

Daily monitoring with Slack alerts:

{
    "apiToken": "apify_api_YOUR_TOKEN_HERE",
    "hoursBack": 24,
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "failureThreshold": 0.1
}

Weekly fleet review (no alerts):

{
    "apiToken": "apify_api_YOUR_TOKEN_HERE",
    "hoursBack": 168,
    "failureThreshold": 0.25
}

Post-deployment quick check with tight threshold:

{
    "apiToken": "apify_api_YOUR_TOKEN_HERE",
    "hoursBack": 4,
    "failureThreshold": 0.05
}

Input tips

• Start with defaults — hoursBack: 24 and failureThreshold: 0.1 cover the most common daily monitoring use case without requiring any changes.
• Use a tight threshold after deployments — Set failureThreshold: 0.02 after pushing code to catch even minor regressions before they compound.
• Connect a webhook from the start — Even if you don't need it today, a Slack webhook transforms this from a tool you run manually into an automated alert system.
• Run weekly for trend visibility — A hoursBack: 168 run gives you week-over-week trend data that a daily run cannot provide.
• Keep the API token as a stored secret — Use Apify's input secret field so the token is never visible in run logs or shared run configurations.

Output example

Single actor report record (one per actor with failures):

{
    "actorName": "website-contact-scraper",
    "actorId": "BCq991ez5HObhS5n0",
    "status": "WARNING",
    "failedRuns": 3,
    "totalRuns": 50,
    "failureRate": 0.06,
    "trend": "improving",
    "trendDetail": "6% now vs 12% previous period",
    "failureCategories": {
        "timeout": 2,
        "schema_mismatch": 1
    },
    "estimatedRevenueLoss": 0.45,
    "latestFailureLog": "2026-03-18T14:28:12.341Z ERROR pushData validation failed — field 'emails' expected type array but received string. Check output schema at actor settings.",
    "recommendations": [
        "2 runs timed out — consider increasing timeoutSecs in run configuration or reducing workload per run",
        "1 schema mismatch — check that pushData output matches your dataset schema, or validate with apifyforge-validate before pushing"
    ],
    "publicStats30d": {
        "total": 1840,
        "succeeded": 1731,
        "failed": 62,
        "aborted": 24,
        "timedOut": 23,
        "successRate": 94.1
    },
    "checkedAt": "2026-03-18T14:30:00.000Z"
}

Fleet summary record (always the final record in the dataset):

{
    "type": "summary",
    "totalActors": 47,
    "actorsWithIssues": 5,
    "overallFailureRate": 0.03,
    "estimatedTotalRevenueLoss": 2.30,
    "topIssue": "timeout (affects 3 actors)",
    "alertSent": true
}

Output fields

Actor report fields

Fleet summary fields

Failure categories

How much does it cost to monitor your Apify fleet?

Actor Health Monitor uses pay-per-event pricing — you pay $0.05 per health check run. One run checks your entire fleet regardless of size. Platform compute costs are included.

You can set a maximum spending limit per run to control costs. The actor stops when your budget is reached.

Compare this to dedicated monitoring tools like Datadog or PagerDuty at $15-99/month for equivalent actor fleet coverage — most users of Actor Health Monitor spend under $5/month with daily monitoring and no subscription commitment. Apify's free tier also includes $5 of monthly credits, making the first month free for most usage patterns.

Monitor your Apify fleet using the API

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/actor-health-monitor").call(run_input={
    "apiToken": "YOUR_API_TOKEN",
    "hoursBack": 24,
    "failureThreshold": 0.1,
    "webhookUrl": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if item.get("type") == "summary":
        print(f"Fleet: {item['totalActors']} actors, {item['actorsWithIssues']} with issues")
        print(f"Top issue: {item['topIssue']}")
        print(f"Revenue at risk: ${item['estimatedTotalRevenueLoss']:.2f}")
    else:
        status = item["status"]
        name = item["actorName"]
        rate = item["failureRate"] * 100
        print(f"[{status}] {name}: {rate:.0f}% failure rate ({item['trend']})")
        for rec in item.get("recommendations", []):
            print(f"  → {rec}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/actor-health-monitor").call({
    apiToken: "YOUR_API_TOKEN",
    hoursBack: 24,
    failureThreshold: 0.1,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();

const summary = items.find((i) => i.type === "summary");
console.log(`Fleet: ${summary.totalActors} actors, ${summary.actorsWithIssues} with issues`);
console.log(`Revenue at risk: $${summary.estimatedTotalRevenueLoss.toFixed(2)}`);

const reports = items.filter((i) => i.type !== "summary");
for (const report of reports) {
    const rate = (report.failureRate * 100).toFixed(0);
    console.log(`[${report.status}] ${report.actorName}: ${rate}% failure rate — ${report.trend}`);
    report.recommendations.forEach((rec) => console.log(`  → ${rec}`));
}

cURL

# Start the actor run
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~actor-health-monitor/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "YOUR_API_TOKEN",
    "hoursBack": 24,
    "failureThreshold": 0.1
  }'

# Fetch results (replace DATASET_ID from the run response's defaultDatasetId field)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json"

How Actor Health Monitor works

Phase 1: Fleet discovery

The actor authenticates with the Apify API using your token and fetches your complete actor list via GET /acts?my=true, paginating in batches of 100 until all actors are retrieved. For each actor, it also captures pricingInfos (for revenue calculations) and stats.publicActorRunStats30Days (for public failure detection) from the same response.

Phase 2: Run history filtering and failure counting

For each actor, the actor fetches up to 100 most recent runs via GET /acts/{actorId}/runs?limit=100&desc=true. Runs are then filtered to the current window (startedAt >= cutoff) and to the trend comparison window (startedAt >= trendCutoff and < cutoff). Failures include any run with status FAILED, TIMED-OUT, or ABORTED. Actors with zero runs in the window are silently skipped; actors with zero user-side failures but public failures get a report with failureRate: 0 and public stats included.

Phase 3: Log-based failure diagnosis

For each failed actor, the actor fetches the last 500 characters of run logs for up to 10 recent failures (to respect API rate limits). It tries the direct GET /logs/{runId} endpoint first, then falls back to GET /acts/{actorId}/runs/{runId}/log. Log text is lowercased and matched against pattern sets for each of the 7 failure categories. Failures beyond the 10-log limit are attributed to unknown. The most recent failure log tail is stored as latestFailureLog for direct inspection.

Phase 4: Trend computation, revenue estimation, and alerting

Trend is determined by comparing currentFailRate to previousFailRate with a 2-percentage-point buffer before classifying as improving or worsening. Revenue loss is computed as failedRuns × avgResultsPerRun × pricePerResult, where avgResultsPerRun is derived from stats.outputItems or stats.resultCount across successful runs, and pricePerResult is extracted from the actor's PAY_PER_EVENT pricing configuration (preferring isPrimaryEvent events, falling back to the highest non-start event price). After all actors are processed, if a webhookUrl is configured and at least one actor exceeds failureThreshold, a structured JSON alert payload is POSTed to the webhook endpoint.

Tips for best results

1. Schedule daily with a Slack webhook. The real value of Actor Health Monitor is proactive detection. A daily schedule plus a Slack incoming webhook means you learn about regressions before users do.

2. Use hoursBack: 4 after every deploy. A narrow window immediately after a deployment catches schema breaks and timeout regressions with minimal noise from unrelated historical failures.

3. Sort your output by estimatedRevenueLoss. When you have 5 actors with issues, fixing the one losing $2.50/day before the one losing $0.03/day is straightforward prioritization. Export to CSV and sort by this column.

4. Lower failureThreshold to 0.02 for critical actors. For high-traffic production actors, even a 2% failure rate is worth alerting on. Use the webhook to route critical actor alerts to a dedicated Slack channel.

5. Run weekly with hoursBack: 168 for trend reviews. A weekly run captures failure rate trends that a daily run cannot. Use this for monthly performance reviews or to demonstrate improving reliability over time.

6. Combine with Actor Quality Audit for full portfolio visibility. Health Monitor catches runtime failures; Quality Audit catches structural and schema issues before they cause failures.

7. Check publicStats30d for actors with external users. If an actor shows failedRuns: 0 on your account but publicStats30d.successRate: 78, external users are failing. This is a common source of negative reviews and maintenance flags.

8. Use failureThreshold: 0 during incident response. When debugging, set the threshold to zero so every actor with any failure appears in the output, regardless of how low the rate is.

Combine with other Apify actors

Limitations

• Log diagnosis is heuristic, not deterministic. Failure classification is based on pattern matching the last 500 characters of run logs. Errors with unusual formatting, translated messages, or custom error classes may be categorized as unknown. Always check the latestFailureLog field directly for unrecognized failures.
• 10-log cap per actor. To stay within Apify API rate limits, the actor reads logs for at most 10 failed runs per actor per health check. Actors with 11+ failures in the period will have the remainder attributed to unknown rather than diagnosed categories.
• 100-run window per actor. Only the 100 most recent runs per actor are fetched. High-throughput actors running thousands of times per day may have older runs in the hoursBack window that are not counted.
• Revenue estimates depend on PPE pricing availability. If an actor does not use pay-per-event pricing or the pricing configuration is not accessible, estimatedRevenueLoss will be 0. This does not indicate zero impact — it indicates the estimate could not be calculated.
• No historical comparison across runs. Each health check is a fresh snapshot. The trend comparison is within-run (current window vs. previous window of equal length). For multi-week trends, store dataset results externally.
• Organization-scoped actors require an organization token. If your actors are shared within an Apify organization, you may need to use an organization-level API token rather than a personal token to see all actors.
• Webhook delivery is best-effort. If the webhook endpoint is down or returns a non-200 response, the health check still completes. The alertSent: false flag in the summary indicates webhook delivery failure, but no retry is attempted.
• Public stats are 30-day rolling only. The publicStats30d field reflects the last 30 days regardless of your hoursBack setting. It cannot be narrowed to a specific window.

Integrations

• Zapier — Send the webhook alert payload to Zapier to create Jira tickets, send emails, or update a status dashboard when actors exceed your failure threshold
• Make — Trigger Make scenarios from the webhook to route critical actor failures to on-call engineers via PagerDuty or create linear issues automatically
• Google Sheets — Export the health check dataset to a Google Sheet after each run to maintain a historical log of fleet failure rates over time
• Apify API — Integrate Actor Health Monitor into your CI/CD pipeline to run a post-deploy health check and fail the pipeline if any actor exceeds a 5% failure rate
• Webhooks — Use Apify's native webhooks to trigger a health check automatically after each actor deployment, rather than running on a fixed schedule
• LangChain / LlamaIndex — Feed fleet health reports into an LLM agent for natural-language incident summaries or automated triage suggestions

Troubleshooting

• All actors return status: HEALTHY but I know something is broken. Check two things: first, confirm the affected actor had runs within your hoursBack window (actors with zero runs are skipped). Second, if the broken actor only fails for external users, the issue will appear under publicStats30d rather than in the individual failure counts. Set hoursBack to a wider window or look for the actor in records where failedRuns: 0 but publicStats30d is populated.

• estimatedRevenueLoss is 0 for all actors. This field requires pay-per-event pricing to be configured on each actor. If your actors use compute-unit billing instead of PPE, the revenue estimate cannot be calculated and defaults to 0. The failure counts and categories are still accurate.

• Run takes longer than 5 minutes. For portfolios of 200+ actors where many actors have failures, log retrieval for each failed run adds time. Each log fetch has a 30-second timeout. To speed up runs, reduce hoursBack to limit the number of actors with failures, or run at a time when your actors are less active.

• Webhook is not being sent even though actors are failing. The webhook only fires when at least one actor's failureRate exceeds failureThreshold. If all failing actors are below the threshold, alertSent will be false. Lower failureThreshold (try 0.01) to confirm connectivity, then raise it back to your desired level.

• Some actors are missing from the report. Actors with zero runs in the hoursBack window are intentionally excluded from the dataset. They are counted in totalActors in the fleet summary but produce no individual report record. This is by design — an actor with no recent runs has no health data to report.

Responsible use

• This actor only accesses run data and logs from your own Apify account using your API token.
• The API token you provide is used exclusively to call the Apify API on your behalf and is not stored beyond the duration of the run.
• Do not share actor runs that contain your API token with untrusted parties.
• For guidance on Apify API security best practices, see the Apify documentation.

FAQ

How is Actor Health Monitor different from the Apify Console monitoring view?

The Console shows you that individual runs failed. Actor Health Monitor tells you why they failed (7 diagnosed categories), whether failures are getting worse or better compared to the prior period, how much money the failures are costing you, which actors need attention first, and what the specific fix action is. It also surfaces public user failures that would be invisible to you in the Console.

How many actors can Actor Health Monitor check in one run?

There is no hard limit. The actor paginates through all actors in your account in batches of 100. Portfolios of 500+ actors are supported. Runtime scales roughly linearly with the number of actors that have failures, since each failure requires a log fetch.

Does Actor Health Monitor work with actors I do not own?

No. It uses your API token, which only grants access to actors in your account. Organization actors require an organization-level token. It cannot access or monitor other users' actors.

How accurate is the failure diagnosis?

Diagnosis is based on pattern matching the last 500 log characters against known error signatures. In testing, it correctly categorizes approximately 70-80% of failures. The most common miss is unknown for custom application errors that do not use standard error messages. The latestFailureLog field always gives you the raw log snippet to investigate manually.

How much does it cost to run Actor Health Monitor daily?

$0.05 per run. Daily monitoring for one month costs $1.50. Twice-daily monitoring costs $3.00/month. Most users with a portfolio of 20-100 actors find daily monitoring sufficient. Apify's free tier includes $5 of monthly credits, covering the first month of daily monitoring at no cost.

Can I monitor only specific actors instead of my entire fleet?

The current version monitors all actors in your account. You can post-filter the dataset output to focus on specific actor names or IDs. A future version may add input-level filtering. If you have a critical actor you want isolated alerting for, connect a webhook and filter on actorName in your webhook processing logic.

What happens if the webhook endpoint is down when an alert is triggered?

The health check completes normally and the results are saved to the dataset. The fleet summary alertSent field will be false, indicating the webhook delivery failed. No retry is attempted. For mission-critical alerting, use a reliable webhook endpoint like a Slack incoming webhook or a Zapier/Make integration with retry logic.

Is it safe to provide my Apify API token to this actor?

Yes. The token is used only to call the Apify API (api.apify.com/v2) on your behalf. It is declared as a secret input field, meaning it is masked in the Apify Console and never included in run logs. The actor makes no requests to any external service other than the configured webhook URL. Review the source code in the actor's repository if you want to verify the exact API calls made.

How is the trend direction calculated?

The actor computes the failure rate for the current hoursBack window and for the immediately preceding window of equal length. If the current rate is more than 2 percentage points lower, the trend is improving. More than 2 points higher is worsening. Within 2 points is stable. If the previous window had zero failures but the current window has at least one, the trend is new_issue.

Can I schedule this to run automatically?

Yes. Use Apify Schedules to run Actor Health Monitor on any cron schedule — daily at 9am, every 6 hours, or after every deployment. Combined with a webhook URL, scheduling turns it into a continuous fleet monitoring system.

What does a CRITICAL status mean vs. WARNING?

CRITICAL means more than 50% of runs in the monitored period failed — the actor is effectively broken. WARNING means the failure rate is above your configured failureThreshold (default 10%) but below 50%. HEALTHY is used for actors that have no user-side failures but have public failures from other users detected in the 30-day stats.

Is it legal to use Actor Health Monitor?

Yes. It only accesses your own Apify account data using your API token. There is no web scraping, no third-party data collection, and no access to data you do not own. All API calls are made to the official Apify API using standard authentication.

Help us improve

If you encounter issues, you can help us debug faster by enabling run sharing in your Apify account:

1. Go to Account Settings > Privacy
2. Enable Share runs with public Actor creators

This lets us see your run details when something goes wrong, so we can fix issues faster. Your data is only visible to the actor developer, not publicly.

Support

Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page. For custom solutions or enterprise integrations, reach out through the Apify platform.