Actor Failure Tracker

Actor Failure Tracker scans every actor in your Apify account, snapshots their 30-day run statistics, and reports which actors gained new failures since the last check. If you manage more than a handful of actors, this is the fastest way to know what broke overnight before your users do.

Schedule it daily and it becomes your automated quality gate: each run compares the current 30-day failure counts against the previous snapshot, isolates the delta, ranks actors by new failure count, and optionally fires a webhook alert to Slack, Discord, or any HTTP endpoint when failures exceed your threshold.

What data can you extract?

Why use Actor Failure Tracker?

Checking actor health manually means opening the Apify Console, clicking into each actor, reading the run history, and deciding whether any uptick in failures is significant. For a portfolio of 20+ actors, that is 30-60 minutes of repetitive work with no audit trail.

This actor automates the entire process. It calls the Apify API, reads publicActorRunStats30Days for every actor you own, diffs the counts against the previous run's stored snapshot, and produces a ranked failure report in under two minutes.

• Scheduling — run daily, nightly, or hourly; the snapshot persists in the actor's key-value store between runs so every diff is accurate
• API access — trigger runs from Python, JavaScript, or any HTTP client to integrate failure tracking into your CI/CD or monitoring stack
• Webhook alerts — POST a structured JSON payload to Slack, Discord, PagerDuty, or any endpoint the moment new failures exceed your threshold
• Monitoring — get Slack or email alerts via Apify's native notification system when the tracker run itself fails
• Integrations — connect results to Zapier, Make, Google Sheets, or any downstream tool that accepts Apify dataset output

Features

• Snapshot-based diffing — saves the current 30-day stats to key-value store after every run and diffs against them on the next run, so you see exactly what changed between checks rather than cumulative totals
• Three failure categories — tracks FAILED, ABORTED, and TIMED_OUT runs separately so you can distinguish hard errors from user cancellations and hung jobs
• Fleet-wide summary — single output record covers all actors: total runs, total failures, new runs since last snapshot, new failures since last snapshot, actor count, healthy actor count
• Per-actor 30-day success rate — computed as round((succeeded / total) * 100, 2) for every actor with failures, giving you an at-a-glance health percentage
• Ranked failure list — actors sorted descending by total new failures (failed + aborted + timed-out), so the worst offender is always first
• Configurable alert threshold — set minFailuresToAlert to suppress webhook noise on low-volume fluctuations (e.g., alert only when 5+ new failures occur)
• Rate-limit-safe API polling — 100ms delay between per-actor detail requests, exponential backoff on 429 responses (2s, 4s, 8s), 30-second request timeout per call
• First-run baseline — on the first run where no snapshot exists, reports existing 30-day failures as the baseline so you immediately see the current state of the fleet
• Graceful error handling — actors that fail to return stats receive zeroed counters rather than crashing the run; errors are logged as warnings
• Pay-per-event pricing — single charge per report run regardless of fleet size; no per-actor fees

Use cases for actor failure tracking

Automated portfolio monitoring for Apify developers

Solo developers and agencies publishing actors on the Apify Store often discover failures through angry user reviews rather than proactive monitoring. Schedule this tracker to run nightly and send a webhook to your Slack. You know about problems the morning after they start, not a week later.

CI/CD quality gates for actor deployments

Teams deploying actor updates can trigger this tracker immediately after deployment to detect regressions introduced by a new build. Compare the post-deploy failure delta against a pre-deploy baseline to confirm whether a deployment made things better or worse.

SLA compliance monitoring for enterprise clients

If you run managed scraping services on Apify and clients depend on specific actors, you need documented evidence that their pipelines are running cleanly. This tracker produces a timestamped daily report that can feed into SLA dashboards or client-facing health status pages.

Failure triage and prioritization

When multiple actors are degraded simultaneously (common after a target website changes its structure), the ranked failure list tells you which actor is impacting the most users and should be fixed first. No more guessing which fire to fight.

Apify account cost auditing

Timed-out and failed runs still consume Apify credits. Tracking new timed-out runs over time helps you identify actors that are consuming credits without producing output, pointing you toward actors that need memory increases, timeout tuning, or code fixes.

How to track actor failures across your portfolio

1. Connect your Apify account — the actor reads your APIFY_TOKEN automatically from the Apify environment; no token input is required when running inside your account.
2. Configure your alert threshold — set Minimum New Failures to Alert to 1 to get notified on every new failure, or raise it to 5 to suppress noise from occasional flaky runs.
3. Add a webhook URL (optional) — paste a Slack incoming webhook URL, Discord webhook URL, or any HTTP POST endpoint to receive structured JSON alerts when the threshold is crossed.
4. Schedule the actor — click "Schedule" in the Apify Console and set it to run daily (e.g., every day at 08:00 UTC). After the first run establishes a baseline, every subsequent run diffs against the previous snapshot and reports only what changed.

Input parameters

Input examples

Daily monitoring with Slack alerts:

{
    "webhookUrl": "https://hooks.slack.com/services/T00000/B00000/XXXXXXXX",
    "minFailuresToAlert": 1
}

High-noise portfolio — alert only on significant degradation:

{
    "webhookUrl": "https://discord.com/api/webhooks/000000/XXXXXXXXX",
    "minFailuresToAlert": 10
}

Silent run — collect report without alerts:

{}

Input tips

• Start with default settings — minFailuresToAlert: 1 ensures you see every failure on day one; you can raise the threshold once you know your portfolio's normal noise floor.
• Use a Slack incoming webhook for the fastest setup — create one at api.slack.com/apps in under two minutes and paste the URL into webhookUrl.
• First run is always a baseline — the first run has no previous snapshot to diff against, so it reports existing 30-day failures rather than "new" ones. This is expected behavior, not a bug.
• Schedule daily for best signal — weekly runs produce larger deltas that are harder to trace to a specific deployment or website change; daily runs keep the diff window small.

Output example

{
    "type": "failure-report",
    "snapshotDate": "2026-03-20",
    "previousSnapshotDate": "2026-03-19",
    "totalActors": 34,
    "totalRuns30d": 4812,
    "totalFailures30d": 187,
    "newRunsSinceLastSnapshot": 143,
    "newFailuresSinceLastSnapshot": 11,
    "actorsWithNewFailures": 3,
    "healthyActors": 31,
    "checkedAt": "2026-03-20T08:02:14.387Z",
    "failures": [
        {
            "actor": "website-contact-scraper",
            "actorId": "tVFYj3uAQSMzaOv2h",
            "newFailed": 6,
            "newAborted": 1,
            "newTimedOut": 0,
            "newTotal": 28,
            "total30d": {
                "failed": 41,
                "aborted": 7,
                "timedOut": 2,
                "succeeded": 198,
                "total": 248
            },
            "successRate30d": 79.84
        },
        {
            "actor": "google-maps-email-extractor",
            "actorId": "aB3kXpQ9mNrLwY7vZ",
            "newFailed": 3,
            "newAborted": 0,
            "newTimedOut": 1,
            "newTotal": 52,
            "total30d": {
                "failed": 9,
                "aborted": 1,
                "timedOut": 3,
                "succeeded": 621,
                "total": 634
            },
            "successRate30d": 97.95
        },
        {
            "actor": "email-pattern-finder",
            "actorId": "cD7rHsT2pKnMuE5yW",
            "newFailed": 0,
            "newAborted": 0,
            "newTimedOut": 0,
            "newTotal": 63,
            "total30d": {
                "failed": 2,
                "aborted": 0,
                "timedOut": 0,
                "succeeded": 311,
                "total": 313
            },
            "successRate30d": 99.36
        }
    ]
}

Output fields

How much does it cost to track actor failures?

Actor Failure Tracker uses pay-per-event pricing — you pay $0.10 per report. Platform compute costs are included. A single report covers your entire actor portfolio regardless of size.

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

Compare this to Datadog or PagerDuty at $15–29/month per seat — with Actor Failure Tracker, most developer accounts spend $3/month with no subscription commitment, and the data lives entirely within your own Apify account.

Track actor failures using the API

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/actor-failure-tracker").call(run_input={
    "webhookUrl": "https://hooks.slack.com/services/T00000/B00000/XXXXXXXX",
    "minFailuresToAlert": 1,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if item.get("type") == "failure-report":
        print(f"Checked {item['totalActors']} actors")
        print(f"New failures: {item['newFailuresSinceLastSnapshot']}")
        print(f"Actors with new failures: {item['actorsWithNewFailures']}")
        for failure in item.get("failures", []):
            print(f"  {failure['actor']}: +{failure['newFailed']} failed, success rate {failure['successRate30d']}%")

JavaScript

import { ApifyClient } from "apify-client";

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

const run = await client.actor("ryanclinton/actor-failure-tracker").call({
    webhookUrl: "https://hooks.slack.com/services/T00000/B00000/XXXXXXXX",
    minFailuresToAlert: 1,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    if (item.type === "failure-report") {
        console.log(`Checked ${item.totalActors} actors`);
        console.log(`New failures: ${item.newFailuresSinceLastSnapshot}`);
        for (const failure of item.failures) {
            console.log(`${failure.actor}: +${failure.newFailed} failed (${failure.successRate30d}% success)`);
        }
    }
}

cURL

# Start the actor run
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~actor-failure-tracker/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://hooks.slack.com/services/T00000/B00000/XXXXXXXX",
    "minFailuresToAlert": 1
  }'

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

How Actor Failure Tracker works

Phase 1: Fleet enumeration

The actor calls GET /v2/acts?my=true&limit=500 using the APIFY_TOKEN injected automatically by the Apify platform. This returns all actors owned by the authenticated account. Each actor is mapped to an ActorListItem record containing its ID, name, and username.

Phase 2: Per-actor stat collection

For each actor, the tracker calls GET /v2/acts/{actorId} and reads data.stats.publicActorRunStats30Days. The raw API response uses uppercase status keys (FAILED, ABORTED, TIMED_OUT, SUCCEEDED, TOTAL) — the parseRunStats function normalizes both cases for compatibility. Requests are issued sequentially with a 100ms inter-request delay to avoid triggering the Apify API rate limiter. A 30-second AbortSignal.timeout is applied to every request. On HTTP 429, exponential backoff doubles the wait from 2 seconds up to three retry attempts.

Phase 3: Snapshot diffing

After collecting current stats, the tracker loads the previous snapshot from the actor's key-value store under the key failure-snapshot. It then computes per-actor deltas using diffStats, which subtracts previous counts from current counts and clamps all values at zero to prevent negative results from API stat resets. On the first run, there is no previous snapshot, so the entire 30-day window is reported as the baseline.

Phase 4: Report assembly and notification

The tracker aggregates deltas into a single FailureReport record, sorts actors by total new failures descending, computes a 30-day success rate for each (round((succeeded / total) * 100, 2)), and counts healthy actors. It writes the report to the dataset, charges the pay-per-event fee, and then — if webhookUrl is set and newFailuresSinceLastSnapshot >= minFailuresToAlert — POSTs a structured JSON payload containing the top 10 failures to the webhook endpoint.

Tips for best results

1. Run the tracker once manually before scheduling — the first run establishes the snapshot baseline. All subsequent scheduled runs will diff against that baseline correctly.

2. Set minFailuresToAlert to match your portfolio's noise floor — if your actors collectively see 2–3 failures per day from legitimate edge cases, set the threshold to 5 so only real regressions trigger your webhook.

3. Combine with Actor Health Monitor — the failure tracker tells you what broke; the health monitor gives deeper context including maintenance flags, zero-run actors, and store listing issues.

4. Inspect successRate30d for triage priority — an actor with successRate30d: 45 is critically broken regardless of how few new failures it has today. Use both the delta and the rate together to prioritize fixes.

5. Use the dataset history for trend analysis — each run appends a report to the dataset. Query the dataset over time to chart success rate trends, identify seasonal patterns, or document fleet health for clients.

6. Separate accounts need separate runs — if you manage actors across multiple Apify accounts, deploy this tracker in each account separately. Each instance reads only the account whose token is active.

7. For large portfolios (50+ actors) — the 100ms inter-request delay means a 50-actor fleet takes approximately 5 seconds to poll. A 200-actor fleet takes ~20 seconds. Well within the 600-second timeout.

Combine with other Apify actors

Limitations

• Requires APIFY_TOKEN in the environment — the actor reads stats only for the account whose token is active. When run from the Apify Console or via API, this token is injected automatically. Custom deployments must set it manually.
• Reports 30-day rolling window stats only — the Apify API exposes only publicActorRunStats30Days. Finer-grained windows (7-day, 1-day) are not available from this endpoint.
• First run produces a baseline, not a diff — on first run, "new failures" equals the 30-day total because there is no previous snapshot to subtract from. Schedule a second run after establishing the baseline to see true deltas.
• Snapshot is stored per actor instance — if you delete the actor and recreate it, the stored snapshot is lost and the next run reverts to baseline behavior.
• Pagination limit of 500 actors — the actor list API call uses limit=500. Accounts with more than 500 actors will see incomplete coverage. This is an Apify API constraint.
• Webhook payload includes top 10 failures only — to keep webhook payloads manageable, only the 10 worst actors are included in the notification. The full list is always in the dataset.
• No per-run-level detail — the actor reports aggregate failure counts, not individual failed run IDs. To inspect specific failing runs, open the Apify Console for the flagged actor or use the Apify Runs API.
• Stats can briefly lag — publicActorRunStats30Days is cached by Apify and may be up to a few minutes behind real time. Running the tracker immediately after a deployment may not reflect the very latest run outcomes.

Integrations

• Zapier — trigger a Zap when a failure report dataset item is created and route the alert to email, Trello, Jira, or any of Zapier's 6,000+ apps
• Make — build automated workflows that parse the failure report, filter actors by success rate threshold, and create tickets in Linear or Asana
• Google Sheets — append each daily failure report to a spreadsheet for trend visualization and long-term portfolio health tracking
• Apify API — trigger runs from your own monitoring scripts, CI/CD pipelines, or internal tools that already use the Apify API
• Webhooks — use the built-in webhookUrl input to push structured failure payloads directly to Slack, Discord, PagerDuty, or any HTTP endpoint
• LangChain / LlamaIndex — feed daily failure reports to an LLM agent that summarizes root cause patterns and suggests remediation steps across your portfolio

Troubleshooting

• Output shows error: true with message "APIFY_TOKEN environment variable is not set" — this happens when running the actor outside the Apify platform without injecting the token. In the Apify Console this token is always set automatically. For API-triggered runs, the token in your API call URL is used to authenticate; no additional token input is needed.

• All actors show zero new failures on every run — confirm the actor ran at least twice. The first run saves a baseline snapshot but reports 30-day historical failures, not live deltas. Only from the second run onward does the diff produce true "since last snapshot" values.

• Webhook is not firing — verify that minFailuresToAlert is not set higher than the number of new failures in the report. Also confirm the webhook URL accepts POST requests with Content-Type: application/json. Check the run log for any Webhook POST to ... returned HTTP 4xx warning messages.

• Some actors appear with zero stats despite active runs — the Apify detail API call for that actor may have failed transiently. The actor logs a warning and records zero stats rather than crashing. Re-run the tracker; the next run will attempt the detail call again.

• Run times out with a very large portfolio — the default 600-second timeout supports up to approximately 6,000 actors at 100ms per request. If you have a portfolio near this scale, increase memory to 512 MB and contact Apify support to confirm API rate limits for your account tier.

Responsible use

• This actor only accesses run statistics for actors owned by the authenticated account.
• It does not access other users' actors, private data, or user-generated content.
• All API calls are made to the official Apify API using your own token.
• Rate limiting and retry logic is implemented to avoid placing excessive load on the Apify API.
• Run history data from this tracker should not be shared publicly without removing account-identifying information.

FAQ

How does Actor Failure Tracker know which actors belong to my account? It calls GET /v2/acts?my=true using your APIFY_TOKEN. This returns only actors owned by the authenticated account — it never accesses other users' data.

How many actors can Actor Failure Tracker check in one run? The actor list API call uses limit=500, so it covers portfolios up to 500 actors. At 100ms per actor detail request, a 100-actor portfolio takes about 10 seconds. A 500-actor portfolio takes around 50 seconds, well within the 600-second timeout.

Does Actor Failure Tracker alert me when an actor has zero runs? Not directly — it reports actors that gained new FAILED, ABORTED, or TIMED_OUT runs. Actors with zero total runs will not appear in the failures list. Use Actor Health Monitor to detect actors with no recent activity.

How is "new failure" defined in the context of this tracker? A new failure is any run that completed with status FAILED, ABORTED, or TIMED_OUT and was not counted in the previous snapshot. The tracker subtracts the previous snapshot's cumulative 30-day counts from the current counts; the difference is the number of failures that occurred since the last check.

What happens if I run Actor Failure Tracker more than once per day? Each run overwrites the stored snapshot with fresh data. If you run it twice within the same day, the second run diffs against the first run of that day, not the previous day's baseline. Running multiple times per day is fine — it just shrinks the diff window, which can improve alert precision.

How accurate is the 30-day success rate shown for each actor? The success rate is computed directly from the publicActorRunStats30Days object returned by the Apify API: round((succeeded / total) * 100, 2). It reflects the same data shown in the Apify Console's actor statistics panel. Stats may lag a few minutes behind real-time.

Can I schedule Actor Failure Tracker to run automatically? Yes. In the Apify Console, open the actor, click "Schedules", and set a daily trigger at your preferred time. The snapshot stored in the key-value store persists between scheduled runs, ensuring each diff is accurate.

How is Actor Failure Tracker different from Apify's built-in notifications? Apify's built-in notifications alert you when a single specific run fails. Actor Failure Tracker monitors your entire fleet, compares aggregate stats over time, and identifies which actors are degrading — giving you portfolio-level visibility rather than per-run alerts.

Is it safe to use my API token with this actor? Yes. When you run an actor inside your own Apify account, the platform injects your APIFY_TOKEN automatically into the actor's environment. You never paste a token into the input form. The token is only used to call the official Apify API.

Can I use Actor Failure Tracker with multiple Apify accounts? Not within a single run. Each run reads only the account associated with the active token. To monitor multiple accounts, deploy this actor in each account separately or use separate API-triggered runs with each account's token.

What is the difference between FAILED, ABORTED, and TIMED_OUT runs? FAILED means the actor crashed with an unhandled error. ABORTED means a user or another process manually stopped the run. TIMED_OUT means the run exceeded the configured timeout. All three count as non-successful runs in this tracker's failure calculation.

Is there a way to ignore expected failures for specific actors? Not with a built-in filter today. A practical workaround is to post-process the dataset output in your downstream workflow (Zapier, Make, or code) and filter out actors you consider non-critical before triggering alerts.

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.