ApifyForge Health Monitor -- Actor Fleet Health Check

Monitor the operational health of every actor in your Apify account with a single API call. ApifyForge Health Monitor scans each actor's recent run history, calculates success and failure rates, detects stale actors that have not run in a configurable number of days, and generates actionable recommendations for fixing problems. It assigns each actor a health status -- healthy, warning, or critical -- and computes a fleet-wide health score weighted by run volume. Built to power the ApifyForge dashboard, this actor gives you an instant snapshot of what is working and what needs attention.

Why use ApifyForge Health Monitor?

• Catch failures before users do. Identifies actors with elevated failure rates before they show up in support tickets or revenue drops.
• Stale actor detection. Finds actors that have not run in a configurable number of days (default: 30) so you can deprecate, update, or investigate.
• Actionable recommendations. Does not just report problems -- generates specific recommendations like "Fix actor X -- 23 failures in last 30 days."
• Fleet health score. A single number (0-100%) that tells you how reliable your entire actor portfolio is, weighted by run volume.
• Configurable thresholds. Adjust the failure rate threshold and stale days cutoff to match your SLA requirements.
• Three-tier status system. Each actor gets a clear status: healthy (>99% success), warning (90-99% success or stale), or critical (<90% success).
• Dashboard-ready output. Structured JSON designed to feed directly into ApifyForge for visualization and alerting.

Key Features

• Fetches all actors from your account with full pagination support
• Samples last 100 runs per actor and filters to the 30-day window
• Computes per-actor success rate, failure count, and run volume
• Assigns health status (healthy / warning / critical) based on configurable thresholds
• Detects stale actors based on configurable inactivity period
• Computes fleet-wide health score weighted by run volume
• Generates prioritized recommendations for the top 5 critical actors
• Outputs structured JSON with per-actor health details and fleet summary

How to Use

1. Go to ApifyForge Health Monitor on the Apify Store.
2. Click Try for free.
3. Enter your Apify API Token.
4. Optionally adjust the Failure Threshold (default: 10%) and Stale Actor Threshold (default: 30 days).
5. Click Start.
6. Wait for the run to complete (typically 30-90 seconds depending on fleet size).
7. Review actor health statuses and recommendations in the Dataset tab.

Input Parameters

Parameter	Type	Required	Default	Description
apifyToken	string	Yes	--	Your Apify API token. Find it at https://console.apify.com/settings/integrations
failureThreshold	integer	No	10	Percentage of failed runs to flag an actor as exceeding the failure threshold. Range: 1-100.
staleDays	integer	No	30	Number of days without a run to consider an actor stale. Range: 1-365.

Input Examples

Default health check (10% failure threshold, 30-day stale cutoff):

{
    "apifyToken": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Strict monitoring (5% failure threshold, 14-day stale cutoff):

{
    "apifyToken": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "failureThreshold": 5,
    "staleDays": 14
}

Relaxed monitoring for hobby projects (25% threshold, 90-day stale cutoff):

{
    "apifyToken": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "failureThreshold": 25,
    "staleDays": 90
}

Output Example

{
    "fleetHealthScore": 96.8,
    "healthyCount": 185,
    "warningCount": 19,
    "criticalCount": 7,
    "actors": [
        {
            "name": "google-maps-scraper",
            "id": "abc123",
            "runs30d": 8421,
            "succeeded30d": 8390,
            "failed30d": 31,
            "successRate": 99.6,
            "lastRunAt": "2026-03-16T12:15:00.000Z",
            "status": "healthy",
            "issues": []
        },
        {
            "name": "broken-api-wrapper",
            "id": "fail02",
            "runs30d": 45,
            "succeeded30d": 28,
            "failed30d": 17,
            "successRate": 62.2,
            "lastRunAt": "2026-03-15T09:00:00.000Z",
            "status": "critical",
            "issues": [
                "Critical failure rate: 38% of runs failed",
                "Exceeds 10% failure threshold"
            ]
        },
        {
            "name": "legacy-email-parser",
            "id": "stale01",
            "runs30d": 0,
            "succeeded30d": 0,
            "failed30d": 0,
            "successRate": 100,
            "lastRunAt": "2025-12-01T08:00:00.000Z",
            "status": "warning",
            "issues": [
                "No runs in 106 days"
            ]
        }
    ],
    "staleActors": [
        { "name": "legacy-email-parser", "id": "stale01", "lastRunAt": "2025-12-01T08:00:00.000Z", "daysSinceLastRun": 106 },
        { "name": "old-rss-reader", "id": "stale02", "daysSinceLastRun": -1 }
    ],
    "recommendations": [
        "7 actor(s) have critical failure rates. Investigate immediately.",
        "19 actor(s) have not run in 30+ days. Consider deprecating or updating.",
        "Fix \"broken-api-wrapper\" — 17 failures in last 30 days (62.2% success rate).",
        "Fix \"unstable-scraper\" — 12 failures in last 30 days (71.4% success rate)."
    ],
    "checkedAt": "2026-03-16T14:30:00.000Z"
}

Output Fields

Field	Type	Description
fleetHealthScore	number	Fleet-wide success rate (0-100%), weighted by each actor's run volume. Higher is better.
healthyCount	number	Number of actors with "healthy" status (>99% success rate, not stale)
warningCount	number	Number of actors with "warning" status (90-99% success rate, or stale)
criticalCount	number	Number of actors with "critical" status (<90% success rate)
actors	array	Per-actor health details. Each entry contains the fields below.
actors[].name	string	Actor name
actors[].id	string	Actor ID
actors[].runs30d	number	Total runs in the last 30 days
actors[].succeeded30d	number	Successful runs in the last 30 days
actors[].failed30d	number	Failed runs in the last 30 days
actors[].successRate	number	Success rate as a percentage (0-100)
actors[].lastRunAt	string	ISO 8601 timestamp of the last run, if available
actors[].status	string	Health status: "healthy", "warning", or "critical"
actors[].issues	array	List of issue descriptions found for this actor
staleActors	array	Actors with no runs in the configured stale period. Each entry has name, id, optional lastRunAt, and daysSinceLastRun (-1 if never run).
recommendations	array	Actionable text recommendations sorted by priority
checkedAt	string	ISO 8601 timestamp of when the health check was performed

Programmatic Access

Python

from apify_client import ApifyClient

client = ApifyClient("apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")

run = client.actor("ryanclinton/apifyforge-health-monitor").call(
    run_input={
        "apifyToken": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "failureThreshold": 10,
        "staleDays": 30
    }
)

dataset_items = client.dataset(run["defaultDatasetId"]).list_items().items
health = dataset_items[0]

print(f"Fleet health score: {health['fleetHealthScore']}%")
print(f"Healthy: {health['healthyCount']} | Warning: {health['warningCount']} | Critical: {health['criticalCount']}")

for rec in health["recommendations"]:
    print(f"  - {rec}")

for actor in health["actors"]:
    if actor["status"] == "critical":
        print(f"  CRITICAL: {actor['name']} ({actor['successRate']}% success, {actor['failed30d']} failures)")

JavaScript

import { ApifyClient } from "apify-client";

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

const run = await client.actor("ryanclinton/apifyforge-health-monitor").call({
    apifyToken: "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    failureThreshold: 10,
    staleDays: 30,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const health = items[0];

console.log(`Fleet health: ${health.fleetHealthScore}%`);
console.log(`Critical actors: ${health.criticalCount}`);

health.recommendations.forEach((rec) => console.log(`  - ${rec}`));

cURL

# Start the health check
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~apifyforge-health-monitor/runs?token=YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"apifyToken": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx", "failureThreshold": 10, "staleDays": 30}'

# Fetch results from the default dataset
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN"

How It Works

ApifyForge Health Monitor runs a systematic health check pipeline:

1. Actor enumeration. Calls GET /v2/acts?my=true with pagination to retrieve every actor in your account.

2. Run history sampling. For each actor, fetches the last 100 runs via GET /v2/acts/{actorId}/runs?limit=100&desc=true. Filters to runs started within the last 30 days.

3. Success/failure analysis. Counts runs by status (SUCCEEDED, FAILED) within the 30-day window. Computes the success rate as succeeded / total * 100.

4. Health status assignment. Each actor receives one of three statuses:

   • Healthy: Success rate >= 99% and not stale
   • Warning: Success rate 90-99%, or stale (no runs within staleDays), or failure rate exceeds the configured threshold
   • Critical: Success rate < 90%

5. Stale detection. Checks each actor's lastRunStartedAt timestamp against the staleDays cutoff. Actors that have never been run are also flagged.

6. Fleet health score. Computes a weighted average success rate across all actors, where each actor's contribution is proportional to its run volume. This prevents low-traffic actors from skewing the overall score.

7. Recommendation generation. Produces actionable text recommendations: counts of critical/stale actors, and specific fix suggestions for the top 5 critical actors by name.

8. Output. Pushes the complete health report to the default dataset and charges one PPE event.

How Much Does It Cost?

ApifyForge Health Monitor uses Pay-Per-Event pricing at $0.05 per health check.

Scenario	Events	Cost
One-time health check	1	$0.05
Weekly monitoring (4x/month)	4	$0.20
Daily monitoring (30x/month)	30	$1.50
Hourly monitoring (720x/month)	720	$36.00

Platform compute costs also apply based on memory and runtime. A typical health check of 200 actors completes in under 90 seconds using 256 MB of memory.

Tips

• Set up alerts. Schedule the health monitor to run daily and use Apify webhooks to trigger Slack or email alerts when criticalCount > 0.
• Tune thresholds to your SLA. If you promise 99.9% uptime, set failureThreshold to 1. If you run experimental actors, 25% may be more appropriate.
• Use staleDays strategically. Set it to 7 for production actors that should run daily, or 90 for seasonal actors that run quarterly.
• Combine with fleet analytics. Run the Health Monitor alongside Fleet Analytics to correlate failure rates with revenue impact.
• Track trends. Each run produces a new dataset entry with a checkedAt timestamp. Schedule daily runs and query the dataset historically to track whether fleet health is improving or degrading.

Limitations

• Run sampling cap. Only the last 100 runs per actor are fetched. For actors with very high run volumes (hundreds per day), some runs outside the sample may be missed.
• No real-time monitoring. This is a batch health check, not a real-time alerting system. For real-time monitoring, schedule frequent runs or use Apify webhooks.
• Status simplification. The three-tier status system (healthy/warning/critical) is intentionally simple. Actors in the "warning" state may have very different issues (stale vs. slightly elevated failures).
• API rate limits. For fleets of 500+ actors, the health check makes hundreds of API calls. The 5-minute timeout is sufficient for most accounts, but very large fleets may need increased timeout settings.

Frequently Asked Questions

What counts as a "failed" run? Any run with a status of FAILED. This includes runs that crashed, timed out, or threw an unhandled exception. Runs with status ABORTED or TIMED-OUT are counted separately and not included in the failure rate calculation shown here.

How is the fleet health score different from a simple average? The fleet health score is weighted by run volume. An actor with 10,000 runs and 99% success contributes much more to the score than an actor with 2 runs and 50% success. This prevents rarely-used actors from disproportionately pulling down the fleet score.

Can I monitor someone else's actors? No. The actor uses ?my=true to fetch only actors owned by the authenticated user. You cannot monitor actors from other accounts.

What does daysSinceLastRun: -1 mean in staleActors? A value of -1 indicates the actor has never been run. There is no lastRunStartedAt timestamp available.

Integration with ApifyForge Dashboard

This actor is one of five data sources that power the ApifyForge dashboard. When connected, health data is visualized as a fleet health heatmap, with color-coded actor cards showing healthy (green), warning (yellow), and critical (red) statuses. Historical health data enables trend analysis so you can see whether fixes are working and spot regression before it impacts users. Schedule this actor to run daily for continuous monitoring.