ApifyForge FAQ — Frequently Asked Questions

Question 1

What is ApifyForge?

Accepted Answer

ApifyForge is an independent platform for discovering, comparing, and managing Apify web scraping actors and MCP intelligence servers. It provides quality scores, cost estimates, 20 side-by-side comparison pages, and 15 developer tools. ApifyForge is not affiliated with Apify; it is built by an independent developer publishing as ryanclinton on the Apify Store.

Question 2

How much does ApifyForge cost?

Accepted Answer

ApifyForge has no platform fee and no subscription. Each actor is individually priced via Apify pay-per-event, charged through your own Apify account — see each actor's Apify Store listing for its current per-event price. Apify offers a free tier with $5 of monthly credits, so you can try actors without paying upfront.

Question 3

Is ApifyForge safe to use?

Accepted Answer

Yes. ApifyForge stores zero API tokens on its servers. Your Apify API token stays on your local machine — the CLI communicates directly with the Apify API and uploads only computed analytics (revenue, success rates, quality scores) to your dashboard. Dashboard login uses GitHub or Google OAuth, fully decoupled from your Apify credentials. See apifyforge.com/security for full details.

Question 4

How is ApifyForge different from the Apify Store?

Accepted Answer

The Apify Store is where actors are published and run. ApifyForge adds a layer on top: quality scores, cost calculators, side-by-side comparisons, developer tools (schema validator, test runner, regression suite), and portfolio analytics. Think of ApifyForge as a dashboard and toolkit for getting more out of the Apify ecosystem.

Question 5

Can I use ApifyForge without an Apify account?

Accepted Answer

Yes. You can browse the actor directory, read comparisons, use the glossary, and explore learn guides without an account. You only need to connect an Apify account to use the dashboard, run actors through developer tools, or see your portfolio analytics.

Question 6

How many actors does ApifyForge track?

Accepted Answer

ApifyForge currently indexes Apify actors and MCP intelligence servers across categories including lead generation, SEO tools, compliance screening, ecommerce intelligence, cybersecurity, financial intelligence, and social media. New actors are added regularly.

Question 7

What is the best Apify actor for lead generation?

Accepted Answer

It depends on your use case. For local business leads from Google Maps, use Google Maps Email Extractor. For enriched leads with quality scores, use B2B Lead Gen Suite. For contact enrichment from company websites, use Website Contact Scraper. Compare them side-by-side on our comparison page at apifyforge.com/compare/lead-generation.

Question 8

How much does web scraping cost with Apify?

Accepted Answer

Most Apify actors use pay-per-event pricing, typically $0.05–$0.50 per result. For example, scraping 100 business contacts from Google Maps costs about $15. Apify includes a free tier with $5/month of credits. Use our cost calculator at apifyforge.com/tools/cost-calculator to estimate costs before running any actor.

Question 9

Is web scraping legal?

Accepted Answer

Web scraping of publicly available data is generally legal in the US and EU. The US Ninth Circuit Court of Appeals ruled in hiQ Labs v. LinkedIn (2022) that scraping publicly accessible data does not violate the Computer Fraud and Abuse Act (CFAA). However, you must respect robots.txt directives, terms of service, and data protection laws like GDPR and CCPA. Do not scrape personal data without a lawful basis, and never use scraped data for spam or harassment.

Question 10

What are the developer tools on ApifyForge?

Accepted Answer

ApifyForge provides 14 developer tools: Cost Calculator, Output Guard, Deploy Guard, Cloud Staging, Schema Diff, Regression Suite, LLM Optimizer, Compliance Scanner, Input Guard, Proxy Analyzer, Plan Advisor, Pipeline Preflight, Schema Registry, and Exposure Report. Each tool is individually priced via Apify pay-per-event — see each tool's Apify Store listing for its current per-event price.

Question 11

Can I compare Apify actors side by side?

Accepted Answer

Yes. ApifyForge has 20 comparison pages covering lead generation, contact scrapers, review scrapers, compliance screening, SEO tools, ecommerce intelligence, security tools, and more. Each comparison shows feature matrices, pricing, best-for recommendations, and a recommender link. Browse all comparisons at apifyforge.com/compare.

Question 12

How do I choose the right Apify actor?

Accepted Answer

Start with the actor recommender at apifyforge.com/recommend — describe your use case and get personalized suggestions. You can also browse by category in the actor directory, use comparison pages to evaluate similar actors, and check quality scores and maintenance pulse data on each actor detail page.

Question 13

What is pay-per-event pricing on Apify?

Accepted Answer

Pay-per-event (PPE) is Apify's pricing model where you pay a fixed amount per result — for example, $0.15 per business contact extracted. Platform compute costs are included in the price. You can set spending limits per run, and unused credits carry over. This is different from time-based pricing where you pay for compute time regardless of results.

Question 14

Can I schedule Apify actors to run automatically?

Accepted Answer

Yes. The Apify platform supports scheduled runs at any interval — hourly, daily, weekly, or custom cron expressions. You can also trigger runs via the API from Python, JavaScript, or any HTTP client. ApifyForge does not manage schedules directly, but actors run on your Apify account where scheduling is built in.

Question 15

Does ApifyForge work with AI agents and MCP?

Accepted Answer

Yes. ApifyForge tracks MCP (Model Context Protocol) servers that expose Apify actors as tools for AI agents. Actors can be integrated with LangChain, LlamaIndex, and other AI frameworks via the Apify integration libraries.

Question 16

How do I export data from Apify actors?

Accepted Answer

Actor results are stored in Apify Datasets. You can download data as JSON, CSV, Excel, or XML from the Apify Console. You can also access results programmatically via the Apify API, or push data directly to Google Sheets, HubSpot, Slack, or any webhook endpoint using Apify integrations.

Question 17

What happens if an Apify actor fails?

Accepted Answer

When an actor fails, Apify logs the error in the run details. Common causes include website blocks (use proxy configuration), timeouts (increase memory or timeout settings), and input validation errors. ApifyForge's health monitor tracks failure rates across your portfolio. Check our debugging guide at apifyforge.com/help/how-do-i-debug-a-failed-apify-actor-run.

Question 18

Can I use Apify actors with Python?

Accepted Answer

Yes. The official apify-client Python package lets you trigger actor runs, read datasets, and manage your account from Python. Install with pip install apify-client. The package supports Python 3.8+ and provides both synchronous and asynchronous clients. ApifyForge's actor detail pages show ready-to-use API code examples in Python, JavaScript, and cURL for every actor.

Question 19

How does ApifyForge work?

Accepted Answer

ApifyForge gives you fleet-level control over every actor you own through a CLI-first workflow. It pulls run history, revenue data, quality scores, and Store rankings into a single dashboard with 15 developer tools not found in the Apify Console.

To get started, sign in with GitHub or Google at apifyforge.com/connect, then run `npx apifyforge init` in your terminal. The CLI authenticates your dashboard session and prompts for your Apify API token (from your APIFY_TOKEN environment variable, .env file, or paste). Your token never leaves your machine — the CLI uses it locally to communicate with the Apify API, then uploads only computed results to your dashboard. ApifyForge indexes Apify actors and MCP intelligence servers across 8 categories, all searchable with side-by-side comparisons and cost calculators. The entire setup takes under two minutes and works with any Apify plan, including the free tier.

The 15 developer tools cover the gaps the Apify Console doesn't address. The Output Guard checks actor output against its declared dataset schema before you push to production. The Deploy Guard executes regression tests across your entire fleet in one click. Revenue Tracking shows PPE earnings per actor over time with trend lines. Bulk Metadata Operations update titles, descriptions, and SEO fields across multiple actors in a single action. The Cost Calculator estimates run costs before you commit credits. The Cloud Staging tool tests actors in Apify's production environment without affecting your live builds.

ApifyForge has no platform fee or subscription. Each actor is individually priced via Apify pay-per-event, billed by Apify on your own account — see each actor's Apify Store listing for its current per-event price. According to Apify's pricing page, Apify's free tier includes $5 of monthly platform credits, which covers most testing workflows.

ApifyForge exists for developers managing 10 or more actors who need fleet-level visibility into earnings, failures, and quality scores. According to Apify's maintenance policy, 2 failed auto-tests within 3 days triggers a maintenance flag, and 28 more days without a fix leads to deprecation. ApifyForge catches these issues early. Visit apifyforge.com to connect your account. See the related question on how ApifyForge is priced, or check apifyforge.com/glossary/ppe for Pay Per Event pricing details.

Question 20

How is ApifyForge priced?

Accepted Answer

ApifyForge has no platform fee, no subscription, and no premium tiers. Each actor is individually priced via Apify pay-per-event — see each actor's Apify Store listing for its current per-event price. Every run is billed by Apify directly on your own Apify account, not through ApifyForge.

Each tool page in ApifyForge displays the exact cost breakdown before you run anything. You trigger every run manually; nothing runs in the background or on a schedule unless you configure one yourself in Apify. You control all costs.

ApifyForge does not monetize your data, display ads, or sell premium features. The same tools available on day one are the same tools used by developers managing Apify actor portfolios. ApifyForge helps Apify developers build better actors, earn more PPE revenue, and manage larger fleets without paying a subscription on top of Apify.

To get started, you need an Apify account with an API token. According to Apify's pricing page, the free tier includes $5 of monthly platform credits, 10 GB of data transfer, and 7-day data retention with full API access — enough to explore ApifyForge and run your first tests.

Visit apifyforge.com to connect your account. See the related question about how much Apify costs, or visit apifyforge.com/glossary/ppe for a breakdown of Pay Per Event pricing.

Question 21

Do I need an Apify account?

Accepted Answer

Yes, you need an Apify account with an API token to use ApifyForge. ApifyForge connects directly to the Apify API to pull your actor data, run history, and revenue figures. Without a connected account, no features will work. Signing up at apify.com is free and takes about two minutes.

According to Apify's pricing page, the free tier includes $5 of monthly platform credits, 10 GB of data transfer, and 7-day data retention. You get full access to the Apify Store, API, and CLI. That is enough to start developing actors, running tests, and exploring ApifyForge.

Here is how to connect step by step. 1) Sign up or log in at apify.com. 2) Go to console.apify.com/account/integrations and click Create Token. 3) Copy the token. 4) Sign in at apifyforge.com/connect with GitHub or Google. 5) Run `npx apifyforge init` in your terminal — the CLI prompts for your token and stores it locally on your machine. Your dashboard populates as the CLI syncs data from your Apify account. Create a dedicated token for ApifyForge rather than reusing your primary token, so you can revoke it independently.

Once you start publishing actors, users who run them generate revenue through Apify's Pay Per Event (PPE) pricing system. Pay Per Event pricing charges users per result delivered, with developers earning 80% of the event fee and Apify retaining 20% for platform costs. For many active developers, PPE revenue covers or exceeds their Apify subscription. ApifyForge tracks earnings across your entire fleet, identifies top performers, and flags actors with quality issues that reduce Store visibility.

See the related questions about how much Apify costs and whether Apify has a free tier. Visit apifyforge.com to connect your account.

Question 22

What makes ApifyForge different from the Apify Console?

Accepted Answer

ApifyForge manages your entire actor portfolio as a fleet, while the Apify Console manages actors one at a time. ApifyForge adds fleet-level analytics, bulk operations, quality monitoring, and 15 developer tools that don't exist in the Console. Both platforms work together through the same Apify API without conflicts.

The Apify Console handles single-actor tasks well. You can view settings, check run history, browse dataset output, and configure builds. But every action targets one actor. Checking success rates across 50 actors means opening 50 pages. Updating metadata on 20 actors means 20 separate form submissions. Finding which actor earned the most PPE revenue last month requires manual calculation.

ApifyForge solves these fleet-scale problems. Fleet Analytics shows revenue, success rates, run counts, and quality scores across every actor in one view. Revenue Tracking displays PPE earnings per actor with trend lines. Quality Score Monitoring tracks schema compliance, success rate, metadata completeness, and build freshness, then alerts you when any actor drops below threshold. Bulk Metadata Operations update titles, descriptions, and categories across multiple actors in a single action. The Output Guard checks output against declared schemas locally before you push. The Deploy Guard runs regression tests across your fleet before deployment.

ApifyForge indexes Apify actors and MCP intelligence servers with side-by-side comparisons and cost calculators. According to Apify's maintenance policy, 2 failed auto-tests within 3 days triggers a maintenance flag, and 28 more days without a fix leads to deprecation. ApifyForge's quality monitoring catches these issues before they affect your Store visibility.

Most developers start using ApifyForge when they hit 10-15 actors and realize the Console workflow doesn't scale. Visit apifyforge.com to see the dashboard. See the related questions about the Output Guard, Deploy Guard, and Cloud Staging for details on specific tools.

Question 23

How much does Apify cost?

Accepted Answer

Apify costs $0 on the free tier, $49 per month on the Personal plan, and $499 per month on the Team plan. Each paid plan includes platform credits equal to the subscription price, covering compute time, data transfer, and proxy usage for actor runs. Enterprise pricing is custom and negotiated directly.

Here is how each tier breaks down. The Free plan includes $5 of monthly platform credits, 10 GB of data transfer, 7-day data retention, and full access to the Store, API, and CLI. The Personal plan at $49 per month includes $49 of credits, 30-day data retention, residential proxy access, and higher concurrency. The Team plan at $499 per month adds team management, 90-day data retention, and dedicated support.

Platform credits are consumed by CPU and memory usage during actor runs, data transfer, proxy bandwidth, and storage. The actual cost depends on your actor's resource needs. A lightweight Cheerio-based scraper processing 1,000 pages might cost $0.10 in credits. A Playwright-based scraper rendering JavaScript on the same pages might cost $0.50 or more. The free tier does not include residential proxies, which are needed for sites with strong anti-bot protection.

Apify's free tier includes $5 of monthly platform credits, 10 GB of data transfer, and 7-day data retention with full API access. Apify also offers Pay Per Event (PPE) pricing for published actors. When users run your PPE-enabled actors, they pay per result delivered, per page scraped, or per search performed. Developers earn 80% of the event fee and Apify retains 20% for platform costs. You set the price per event and earn revenue automatically.

Developers with 10 or more published actors often earn more in PPE revenue than they spend on their Apify subscription, making the platform self-funding. ApifyForge tracks both sides of this equation, showing PPE earnings alongside platform costs so you can see your net position at a glance. Visit apifyforge.com/tools/cost-calculator to estimate costs for specific actors. See the related questions about whether Apify has a free tier and how PPE pricing works at apifyforge.com/glossary/ppe.

Question 24

Is Apify free?

Accepted Answer

Yes, Apify offers a free tier that lets you develop actors, run scraping jobs, and explore the platform without paying anything. The free plan includes $5 of monthly platform credits, 10 GB of data transfer, and full access to the Apify Store, API, CLI, and all core platform features.

Here is what you can realistically do with the free tier. The $5 of monthly credits is enough to develop and test actors locally using the Apify CLI, run small to medium scraping jobs (a few thousand pages per month depending on complexity), experiment with different actor templates and frameworks (Cheerio, Playwright, Puppeteer), publish actors to the Apify Store, and access datasets and key-value stores for data management. You also get access to the full Apify API, which means ApifyForge works perfectly with a free account.

There are some limitations to be aware of. The free tier does not include residential proxies, which are essential for scraping websites with strong anti-bot protection like Amazon, LinkedIn, Google, and most social media platforms. If your actors target these sites, you will need a paid plan for proxy access. Data retention on the free tier is 7 days, meaning your datasets and run logs are automatically deleted after a week. Concurrency is also limited, so you cannot run many actors simultaneously.

For many developers, the free tier serves as a development and testing environment. You build and debug your actors on the free plan, then upgrade when you are ready to publish and scale. The Personal plan at $49 per month includes $49 of credits, 30-day data retention, residential proxy access, and higher concurrency limits — which is what most independent developers use for production.

One important note for actor developers: once you start publishing actors with Pay Per Event pricing, users who run your actors generate PPE revenue for you. This means the platform can become self-funding as your actor portfolio grows. Visit apifyforge.com/glossary/ppe for a detailed explanation of how PPE revenue works. For a full comparison of all pricing tiers, see the related question about how much Apify costs.

Question 25

What is the Apify Store?

Accepted Answer

The Apify Store is a public marketplace where developers publish actors (pre-built automation tools) and users discover, run, and pay for them. Think of it as an app store specifically for web scraping, data extraction, browser automation, and AI-powered data processing tools.

The Store contains thousands of actors organized by category — including scraping tools for specific websites (Amazon, LinkedIn, Google Maps, TikTok), general-purpose crawlers, data processing pipelines, AI integrations, and automation workflows. Users find actors through keyword search, category browsing, curated collections, and popularity rankings. Each actor has a dedicated Store page with a description, README documentation, pricing information, input schema, example output, and user reviews.

For developers, the Store is a monetization platform. When you publish an actor with Pay Per Event (PPE) pricing enabled, every user who runs your actor pays per event — per result returned, per page scraped, per search performed, or whatever unit you define. You set the price per event and earn revenue automatically. Apify handles all billing, payment processing, and user management. Your job is to build a useful actor, price it appropriately, and keep it running reliably.

Store visibility is determined by several ranking factors. Quality score is a composite metric based on your actor's success rate, schema compliance, metadata completeness, and build freshness. Usage volume measures how many users run your actor and how often. Metadata relevance determines how well your actor matches search queries based on its title, description, and README content. Actors with higher quality scores and more usage appear higher in search results and category pages.

ApifyForge helps you optimize for these ranking factors with quality score tracking, schema validation, metadata management, and Store analytics. You can see exactly which factors are dragging down your visibility and fix them before they affect your revenue. Visit apifyforge.com/glossary/apify-store for more details on how Store rankings work. For related topics, see the questions about how to get more users for your actor and how much you can earn with Apify actors.

Question 26

How do I connect my Apify account?

Accepted Answer

To connect your Apify account, sign in with GitHub or Google at apifyforge.com/connect, then open Settings → Apify API Token and paste a scoped API token. The whole process takes about two minutes: OAuth sign-in, create a scoped token in Apify (five specific permission boxes), paste it into ApifyForge, and the dashboard begins populating immediately.

## Step 1: Sign in to ApifyForge

Visit [apifyforge.com/connect](https://apifyforge.com/connect) and sign in with your GitHub or Google account. This creates your ApifyForge dashboard account via OAuth — your GitHub or Google identity is how we know it is you, and it is completely separate from your Apify credentials.

## Step 2: Create a scoped Apify API token

Open [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations) in another tab, click Create new token, toggle Limit token permissions, and check exactly five boxes across two dropdowns: **Actors** (Read + Run + List runs) and **Storages** (Read + Write). Leave everything else unchecked — including the entire Tasks section.

The full walkthrough with justifications for each box is in [How do I create a scoped Apify API token for ApifyForge?](/help/create-apify-api-token). Read that article if you want to understand exactly what each permission grants before clicking Save.

## Step 3: Paste the token in Settings

Once you have the scoped token, go to [Settings → Apify API Token](/dashboard/settings) in ApifyForge and paste it in. Click Save. ApifyForge validates the token by calling Apify's `/v2/users/me` endpoint and shows a green connected indicator if it works. The token is immediately encrypted with AES-256-GCM using a server-held key before being written to the database — the plaintext is never persisted on disk.

## Step 4: Run your first Fleet Analysis

Navigate to your dashboard. The first time you land there with a valid token, you will see a FirstRunExperience card with a Get Fleet Health Score button. Click it. ApifyForge triggers the `fleet-analytics` backend actor on your account — typical run time is 2–3 minutes, and you can leave the page while it runs. When it completes, the hero section re-renders with your Fleet Health Score, Action Plan, and whatever else the analytics pass surfaced. A green success pulse flashes for a few seconds to confirm the data is fresh.

## Alternative: the CLI flow (advanced)

If you prefer to keep your token entirely on your own machine and never hand it to ApifyForge's servers, the CLI flow is still available as an advanced alternative. Run `npx apifyforge run <tool>` in your terminal with `APIFY_TOKEN` set in your local environment. The CLI uses your token locally, calls the Apify API, and uploads only the computed results to your dashboard. Both modes produce identical results in the dashboard — the browser flow is just easier for most users because it does not require a local Node install or a terminal.

## Best practices

A few things worth adopting regardless of which flow you pick:

- **Create a dedicated token** for ApifyForge — do not reuse your main Apify token. Use the suggested name `apifyforge-dashboard` so it is identifiable in your Apify audit logs. This limits the blast radius if anything goes wrong and makes it easy to revoke ApifyForge's access without disrupting other integrations.
- **Set a budget alarm** in your Apify account at [console.apify.com/billing](https://console.apify.com/billing). The scoped-token permission model limits what an attacker can do, but it does not limit how much money they can burn through running actors. A budget alarm is your cap on that cost-drain risk and is the single most important safeguard to set up.
- **Rotate every 90 days.** Create a new scoped token, paste it into Settings (it overwrites the old one automatically), then revoke the old one in Apify.
- **Never commit tokens to git.** Obvious but worth saying: add `.env` to your `.gitignore`.

## Related articles

- [What data can ApifyForge access?](/help/what-data-can-apifyforge-access) — exactly what the scoped token does and does not grant
- [How do I create a scoped Apify API token for ApifyForge?](/help/create-apify-api-token) — the full walkthrough with per-permission justifications
- [Do you store my API token?](/help/do-you-store-my-api-token) — how the token is encrypted and stored
- [How do I disconnect my account?](/help/how-do-i-disconnect-my-account) — how to revoke access later

*Last updated: April 14, 2026*

Question 27

What data can ApifyForge access?

Accepted Answer

## What ApifyForge can access With the five scoped permissions (Actors: Read, Run, List runs; Storages: Read, Write), ApifyForge can read: - Your **actor list and metadata** — names, descriptions, pricing model, memory and timeout defaults - Your **build history** for each actor — version numbers, build timestamps, input/output schemas (read-only) - **Run history** for every actor — status, duration, memory consumption, cost per run, failure reasons - The **contents of datasets, key-value stores, and request queues** you own — but see the [Honest disclosure](#honest-disclosure-read-this-if-your-data-is-sensitive) section below for the important scope nuance And with Storages: Write, ApifyForge's backend actors can write: - **Actor OUTPUT** to the default key-value store of each run ApifyForge triggers on your behalf - **Trend snapshots** and acknowledgement state, so next week's run can compute week-over-week deltas and regression detection That is the complete set of what ApifyForge touches on your Apify account. --- ## What ApifyForge cannot access The scoped token does not grant any access to: - ❌ **Your actor source code** — blocked at the Apify platform level, even for full-access tokens - ❌ **Environment variables or secrets** stored in your actor configuration - ❌ **Billing information, payment methods, or usage quotas** - ❌ **Proxy passwords, proxy groups, or proxy configuration** - ❌ **The ability to create, delete, or rename actors** (Actors: Write is not granted) - ❌ **The ability to trigger new builds or manage existing builds** (Actors: Build is left unchecked) - ❌ **Webhooks on your actors** (both webhook permissions left unchecked) - ❌ **Apify Tasks** — the entire Tasks resource group is unchecked; ApifyForge does not use Tasks at all - ❌ **The ability to create new storages** (Storages: Create is left unchecked; Apify auto-creates default storages per run) - ❌ **Schedules, user management, or token management** - ❌ **Any data owned by other Apify users** — the token is scoped strictly to your own account --- ## Honest disclosure (read this if your data is sensitive) Apify's permission schema bundles key-value stores, datasets, and request queues together under a single **Storages: Read** checkbox and does not let you narrow it further. When you grant Storages: Read, the scoped Apify API token can — from an API capability standpoint — fetch the contents of any dataset you own, including datasets produced by your own scrapers that have nothing to do with ApifyForge. **In practice, ApifyForge only reads:** - The specific datasets returned by `run-sync-get-dataset-items` calls initiated by its own backend actors - Specific key-value store keys (like `OUTPUT` and `SIGNALS`) that those actors wrote **The row data of your other datasets — the ones your own scrapers produce — is never fetched by the ApifyForge server, never cached in the ApifyForge database, and never persisted anywhere in ApifyForge infrastructure.** **Enforcement model.** The "we only read our own actors' datasets" guarantee is enforced by ApifyForge's code, not by Apify's permission schema. The only dataset-fetching code paths in `apifyforge/src/lib/apify/runner.ts` are `run-sync-get-dataset-items` calls that ApifyForge itself initiated, plus `getRunResults` lookups for those same run IDs. There is no other dataset-fetching code path. Apify's platform has no per-dataset scoping available in the permission UI, so the technical capability the token grants is wider than the implementation actually uses. **If you consider the contents of your scraped datasets highly sensitive**, you should know the scope is wider than "metadata only" and the guarantee is **procedural rather than technical**. For the strongest isolation, use the CLI flow instead of the browser token flow — the CLI (`npx apifyforge run `) keeps the token entirely on your own machine, so there is no server-side copy to exfiltrate. Both flows produce identical analytics in the dashboard. --- ## Risk level summary ApifyForge data access falls into three risk tiers, from lowest to highest: - 🟢 **Low risk: metadata and run history access.** Actors: Read and Actors: List runs grant read-only access to non-sensitive operational data — actor names, pricing, run status, and cost. A leak of just these permissions would expose operational metadata but no customer data, secrets, or destructive capability. - 🟡 **Medium risk: storage read access.** Storages: Read grants read access to every dataset, key-value store, and request queue you own. In practice ApifyForge only reads datasets it produced, but the token is technically capable of reading all of them. A leak would allow an attacker to read sensitive scraped data if any exists in your account. - 🔴 **Higher risk: storage write access.** Storages: Write is the only genuinely destructive permission in the scoped set. A leaked token could corrupt, overwrite, or delete records in any storage you own. This is the one permission that requires real caution for production accounts. **Overall: moderate risk with strong safeguards when using a scoped Apify API token plus the best practices in [Production hardening](#production-hardening) below.** For high-stakes workloads, use the CLI flow instead — it keeps the token entirely on your own machine. --- ## What each scoped permission grants The scoped token grants exactly five permissions. Here is what each one unlocks, and nothing more. ### Actors: Read **What it grants.** `GET /v2/acts`, `GET /v2/acts/{id}`, and read access to every sub-resource including builds, input schemas, and source metadata. Build-read access is bundled into this permission — the separate Build checkbox is for triggering new builds (write-level), not for reading existing ones. **Which backend actors use it.** Every backend specialist. The `fleet-analytics` orchestrator enumerates your actors as step one of every run. `schema-validator`, `release-gate`, and `compliance-scanner` read your actor definitions to check for drift, breaking changes, or policy violations. `cost-watchdog` matches actor IDs to memory and timeout settings for spend estimates. **With it, you get:** a populated fleet view, Fleet Health Score computation, schema drift detection across builds, and Action Plan "Top fix" cards that reference specific actors. **Without it:** every backend actor fails at step one with `403 Forbidden` on `/acts`. The dashboard is empty. ### Actors: Run **What it grants.** `POST /v2/acts/{id}/runs` and `POST /v2/acts/{id}/run-sync-get-dataset-items` — the trigger-runs permission. **Which backend actors use it.** Every Run button in the dashboard fires `run-sync-get-dataset-items` on one of the backend actors. You pay for these runs on your own account via Apify Pay-Per-Event pricing, which is why ApifyForge only triggers runs when you click Run — it does not run on a schedule or in the background. **With it, you get:** real analytics on demand when you click any Run button. **Without it:** cached data still displays, but every Run button returns 403. The FirstRunExperience on a fresh account never completes. ### Actors: List runs **What it grants.** `GET /v2/acts/{id}/runs` — run history with status, duration, memory consumption, cost per run, plus read access to each run's default dataset and key-value store. **Which backend actors use it.** `fleet-analytics` for failure rate and cost aggregates, `cost-watchdog` for spend-per-actor tracking, `ab-tester` for variant comparison, `quality-monitor` for week-over-week degradation detection. **With it, you get:** real failure rates, real cost numbers, regression signals, and Action Plan items computed from actual history. **Without it:** the dashboard looks populated but every metric is zero. Action Plan is blank or generic. ### Storages: Read **What it grants.** `GET /v2/datasets/{id}/items`, `GET /v2/key-value-stores/{id}/records/{key}`, and equivalent endpoints for request queues — for every storage owned by your account. **Which backend actors use it.** Effectively every backend actor, because `run-sync-get-dataset-items` returns the dataset in the same HTTP response as the run trigger. Without Storages: Read, that combined endpoint fails on the read half with 403 — the run still consumes credits, but the response never includes the data. **Important:** see the [Honest disclosure](#honest-disclosure-read-this-if-your-data-is-sensitive) section above for the crucial nuance — this permission is wider than "datasets ApifyForge produced" and the guarantee is procedural. **Without it:** runs burn credits but the dashboard shows nothing. Worst failure mode. ### Storages: Write **What it grants.** `PUT /v2/key-value-stores/{id}/records/{key}`, `POST /v2/datasets/{id}/items`, and the delete endpoints for storages you own. **Which backend actors use it.** Every backend actor writes its OUTPUT to its default key-value store (standard Apify convention). `fleet-analytics` writes trend snapshots so next week's run can compute week-over-week deltas. The dashboard-native acknowledgement flow (when it ships) will also write per-item ack state here. **⚠️ Destructive-capability warning.** Of the five scoped permissions, Storages: Write is the only one that is genuinely destructive if the token leaks. A stolen token could push malicious data into your datasets, overwrite or delete records in key-value stores, or corrupt run outputs. Read-only permissions cannot do that. Apify's permission schema does not let you narrow write access to "KV stores only" or "our actors' outputs only" — if you grant it, the token can write anywhere in your storages. Mitigations in the [Production hardening](#production-hardening) section below. **Without it:** actor runs fail at the save step. The actor starts, does its work, then crashes when it tries to save. No data persists. The entire backend fleet becomes inoperative. --- ## Blast radius if the token leaks The worst-case damage from a leaked scoped Apify API token is bounded. An attacker could: - **Read** all storages owned by your account, including dataset contents - **Write** to those storages — corrupt, overwrite, or delete records (the destructive risk from Storages: Write) - **Trigger runs** on your actors, burning through Apify credits on your bill An attacker could NOT modify your actors, touch your billing, create new tokens, change your schedules, configure webhooks, or manipulate your account in any other way. The most important mitigation for the cost-drain risk is a budget alarm at [console.apify.com/billing](https://console.apify.com/billing) — that caps how much a compromised token can burn through regardless of application-level protection. --- ## How ApifyForge stores and protects your token Your token is encrypted with **AES-256-GCM** using a 256-bit key held in the server's `TOKEN_ENCRYPTION_KEY` environment variable. The encryption key lives only in the ApifyForge server environment — never in the database, never in logs, never in backups. A full database dump would yield only ciphertext with no way to decrypt it. When an analytics run needs to talk to Apify, the server reads the ciphertext, decrypts it in memory, makes the API call, and discards the plaintext. The plaintext is never logged, never written to a file, and never sent to any third party. **Revocation paths** — either works independently: 1. **In ApifyForge:** Settings → Apify API Token → Delete token. Clears the `encrypted_token` column from the database. ApifyForge can no longer run anything on your account. 2. **In Apify:** [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations), find `apifyforge-dashboard`, click Revoke. Invalidates the token everywhere, not just in ApifyForge. **The definitive off switch** — works even if ApifyForge is unreachable. > **You can revoke access at any time instantly from Apify — this is a one-click hard stop.** No multi-day waiting period, no support ticket, no negotiation. It takes effect immediately because it is enforced by Apify's own API. For the full token storage architecture, see [Do you store my API token?](/help/do-you-store-my-api-token). --- ## Production hardening The scoped token model above is already dramatically safer than a full-access integration, and is fine for most users doing experimentation, side projects, or smaller Apify accounts. But if you are running ApifyForge against a business-critical Apify account where downtime, data corruption, or unplanned spend would cause real revenue loss, layer these additional controls on top of the base setup: - **Rotate the token every 30 days instead of every 90.** A shorter rotation cadence shrinks the window an exfiltrated token could be used in. Production accounts should treat token rotation as monthly hygiene. - **Set a tight budget alarm in Apify** at [console.apify.com/billing](https://console.apify.com/billing). Set a monthly spending cap at roughly 150 percent of your known baseline. This caps cost-drain damage from a leaked token at a known ceiling regardless of any application-level protection. **The single highest-leverage control you can add.** - **Monitor your Apify run history for activity you did not initiate.** Unexpected runs, KV store writes, or dataset pushes are the earliest visible signal of a compromised token. A quick daily glance at [console.apify.com/actors/runs](https://console.apify.com/actors/runs) catches most anomalies. - **Consider the CLI flow instead of the browser token flow.** The CLI (`npx apifyforge run `) keeps the token entirely on your own machine — there is no server-side copy to exfiltrate, so a compromise of ApifyForge's application server cannot leak your token. Both flows produce identical analytics in the dashboard. - **Use a dedicated Apify account for ApifyForge** where possible. The strongest isolation comes from running ApifyForge against an Apify account that contains ONLY the actors you want monitored — separate from your main production account. None of these controls is strictly necessary. The base scoped token model is already safer than any full-access integration. But for high-stakes accounts, layering them on top moves the risk profile from "sensible default" to "hardened for production." --- ## Should you connect your account? **You can safely connect ApifyForge with a scoped token if:** - You want analytics across your Apify actor fleet without building a custom dashboard - You are comfortable granting read + write access to your Apify storages, with a dedicated token and budget alarm in place - You run a small-to-mid-size Apify account where the fleet analytics value justifies the trust trade-off - You understand the [Honest disclosure](#honest-disclosure-read-this-if-your-data-is-sensitive) above about Storages: Read being wider than "metadata only" **You should use the CLI flow instead (or reconsider entirely) if:** - Your datasets contain highly sensitive or regulated data — PII under GDPR, PHI under HIPAA, PCI-DSS-scoped data, customer records - You cannot tolerate any destructive write-level risk on your key-value stores or datasets - Your threat model assumes ApifyForge's application server itself could be compromised - You run a mission-critical production Apify account with no budget alarm in place The CLI flow (`npx apifyforge run `) keeps the token entirely on your own machine and produces identical analytics — no trust trade-off on the server side. --- ## Scoped token vs full-access token For reference, here is what the five-box scoped token grants compared to a full-access token: | Capability | Scoped token | Full-access token | |---|:---:|:---:| | List actors and read metadata | ✅ | ✅ | | Read build history and schemas | ✅ | ✅ | | Trigger actor runs | ✅ | ✅ | | Read run history, cost, duration | ✅ | ✅ | | Read/write your own storages | ✅ | ✅ | | Modify actor source code | ❌ | ❌ (blocked at Apify platform level) | | Delete or rename actors | ❌ | ✅ | | Trigger new actor builds | ❌ | ✅ | | Abort, restart, or modify runs | ❌ | ✅ | | Manage actor webhooks | ❌ | ✅ | | Manage schedules | ❌ | ✅ | | Change Apify billing | ❌ | ❌ (never exposed to any token) | | Create new API tokens | ❌ | ❌ (never exposed to any token) | | Read Apify Tasks | ❌ | ✅ | | **Blast radius if leaked** | **Low** — storages + runs only | **High** — whole account | --- ## Frequently asked questions ### Is ApifyForge safe to use? Yes, when you follow the [token creation guide](/help/create-apify-api-token) — create a scoped token, set a budget alarm, rotate every 90 days, and monitor Apify run history for unexpected activity. ApifyForge restricts data access to exactly what its scoped Apify API token grants: metadata, run history, and your own storage contents. It never sees your actor source code, environment variables, billing, or proxy credentials. With a budget alarm in place, even the cost-drain risk from a leaked token is capped at a known ceiling. The destructive-capability warning around Storages: Write is the one thing that requires careful thought — if your storages contain highly sensitive data, use the CLI flow instead. ### Can ApifyForge see my data? ApifyForge can see your actor metadata, run history, and the contents of storages you own — but not your actor source code, environment variables, billing, or any data owned by other Apify users. Dataset contents specifically: the scoped token technically allows reading every dataset in your account, but ApifyForge's code only reads datasets produced by the backend analytics actors it ran on your behalf. Your other datasets (the ones your own scrapers produced) are never fetched, cached, or persisted anywhere in ApifyForge's systems. See the [Honest disclosure](#honest-disclosure-read-this-if-your-data-is-sensitive) section above for the procedural-vs-technical guarantee. ### Does ApifyForge access my datasets? Only the datasets produced by the backend actors ApifyForge runs on your behalf — not the datasets your own scrapers produce. The scoped token grants read access to all datasets in your account at the permission level, but ApifyForge's code specifically fetches only the datasets returned from `run-sync-get-dataset-items` calls it initiated. Your other datasets' row data is never loaded into memory, never cached, and never persisted on the ApifyForge server. This is a procedural guarantee enforced by ApifyForge's code, not a technical guarantee enforced by Apify's permission schema. If that distinction matters to you, use the CLI flow — it keeps the token entirely on your own machine. ### What data does ApifyForge store in its database? Computed analytics — Fleet Health Score, failure counts, cost aggregates, quality scores, trend deltas — not the raw data those analytics were computed from. The cache contains things like "Fleet Health Score = 64", "actor X failed 3 times this week", "estimated monthly cost = $180" — not the raw dataset rows. The cache is cleared automatically when you delete your token and can be forcibly cleared from Settings at any time. The token itself is separately encrypted with AES-256-GCM using a server-held key; see [Do you store my API token?](/help/do-you-store-my-api-token) for the full storage architecture. ### What happens if my Apify API token leaks? An attacker could read your storages, write to your storages (destructive), and trigger runs on your actors — but nothing else. The scoped token's blast radius is bounded: read metadata, read and write storages, trigger runs. It cannot modify actor code, access billing, create new tokens, or touch anything outside your own storages and runs. Mitigations: set a budget alarm in Apify, monitor run history daily, and revoke the token immediately in Apify at the first sign of compromise. ### Is ApifyForge GDPR-compliant if my datasets contain personal data? Yes, ApifyForge can be used in GDPR-compliant setups — but for datasets containing regulated personal data, the recommended approach is the CLI flow to avoid server-side token storage. ApifyForge does not store your raw dataset contents and only caches computed analytics that are not themselves personal data. The scoped token does technically have read access to every dataset in your account, which means the token itself has the capability to read datasets containing personal data — but ApifyForge's code only reads datasets produced by its own backend actors, not your scrapers' outputs. For regulated data (PII under GDPR, PHI under HIPAA, PCI-DSS-scoped data, etc.), the cleanest architecture is the CLI flow (`npx apifyforge run `), which keeps the token entirely on your own machine and never hands it to any ApifyForge server. Both flows produce identical analytics in the dashboard, so choosing the CLI flow for regulated datasets is a no-compromise decision. --- ## Related articles - [How do I create a scoped Apify API token for ApifyForge?](/help/create-apify-api-token) — the step-by-step walkthrough - [Do you store my API token?](/help/do-you-store-my-api-token) — how the token is encrypted, stored, and revoked - [How do I connect my Apify account?](/help/how-do-i-connect-my-apify-account) — the browser token flow vs the CLI flow - [How do I disconnect my account?](/help/how-do-i-disconnect-my-account) — how to revoke access if you change your mind --- *Last updated: April 14, 2026*

Question 28

Do you store my API token?

Accepted Answer

Yes, when you use the browser-based token flow, ApifyForge encrypts and stores your scoped Apify API token in a PostgreSQL database using AES-256-GCM with a server-held encryption key. This is a deliberate trade-off for usability: it lets the dashboard run actors on your behalf without requiring you to keep a terminal open. If you would rather keep your token entirely on your own machine, the CLI flow is still available and stores nothing on ApifyForge's servers — both modes are supported, and you can choose.

## The browser token flow (stored, encrypted)

When you paste a token into Settings → Apify API Token and click Save, here is exactly what happens:

1. The plaintext token is sent over HTTPS to the ApifyForge server.
2. The server encrypts it with AES-256-GCM using a 256-bit encryption key held in the `TOKEN_ENCRYPTION_KEY` environment variable. The key lives only in the server's environment — it is not written to the database, not logged, and not included in backups.
3. The resulting ciphertext is written to the `users.encrypted_token` column in PostgreSQL, formatted as `ivHex:authTagHex:ciphertextHex`.
4. The plaintext is immediately discarded from memory.

When the dashboard needs to run an actor, the server reads the ciphertext, decrypts it in memory using the same environment key, passes the plaintext to Apify's API as a URL parameter on `run-sync-get-dataset-items`, and discards the plaintext again. The plaintext is never logged, never written to a file, and never sent to any third party.

**Why this is safer than it sounds:** if someone exfiltrated the full PostgreSQL database, they would get ciphertext only. Without `TOKEN_ENCRYPTION_KEY`, the ciphertext is useless — AES-256-GCM with a 256-bit key is computationally infeasible to break. The encryption key lives only on the application server, so a database-only breach yields zero usable tokens.

**Why the risk is not zero:** if someone compromised the application server itself (not just the database), they would have both the ciphertext AND the key, and could decrypt tokens in memory. The mitigation is the scoped-token model: even if your token is exfiltrated, the scoped permissions limit what an attacker can do with it — read metadata, read storages, and trigger runs on your account, but not modify actors, touch billing, or create new tokens. The full scope analysis is in [How do I create a scoped Apify API token for ApifyForge?](/help/create-apify-api-token).

## The CLI flow (not stored)

If you prefer zero server-side storage, run `npx apifyforge run <tool>` instead. Your token lives only in your local `APIFY_TOKEN` environment variable, the CLI uses it locally to call the Apify API, and only the computed results are uploaded to your ApifyForge dashboard via HTTPS. At no point does the token transit through or get stored on ApifyForge infrastructure. Both flows produce identical results in the dashboard — the browser flow is just easier for most users because it does not require a local Node install or a terminal.

## How to revoke access

You can revoke ApifyForge's access at any time in two places. Either one works independently; doing both is belt-and-braces.

**In ApifyForge:** open Settings → Apify API Token and click Delete token. This deletes the encrypted ciphertext from the `users.encrypted_token` column. ApifyForge can no longer run anything on your account after this — any in-flight run completes, but new runs fail with a 'no token configured' error and the dashboard reverts to the ConnectTokenStep state.

**In Apify:** open [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations), find the token you created (whatever name you gave it — `apifyforge-dashboard` is the suggested default), and click Revoke. This invalidates the token everywhere, not just in ApifyForge, which means it is the definitive off switch. Even if ApifyForge were entirely unreachable, this would still work because Apify's own API enforces the revocation.

## Best practices

A few things worth doing regardless of which flow you pick:

- **Create a dedicated token** for ApifyForge — do not reuse your main Apify token. Use the suggested name `apifyforge-dashboard` so it is identifiable in your Apify audit logs.
- **Set a budget alarm** in your Apify account at [console.apify.com/billing](https://console.apify.com/billing). This caps how much a compromised token could burn through regardless of any application-level protection. If a token ever leaks, the budget alarm stops the bleeding.
- **Rotate every 90 days.** Create a new scoped token, paste it into Settings (it overwrites the old one automatically), then revoke the old one in Apify.
- **If you suspect a compromise**, revoke immediately in Apify first, then delete in ApifyForge Settings. Revoking in Apify is the source of truth — it takes effect even if ApifyForge is unreachable.
- **Never commit tokens to git.** Obvious but worth saying: add `.env` to your `.gitignore`.

Your ApifyForge dashboard account is authenticated via GitHub or Google OAuth, completely separate from your Apify credentials. This decoupling means your dashboard identity and your Apify identity are linked only via the encrypted token — revoking one does not automatically revoke the other, but both paths to revocation are straightforward.

For the scope analysis of exactly what the stored token can and cannot do, see [What data can ApifyForge access?](/help/what-data-can-apifyforge-access). For how to fully disconnect and clear your account, see [How do I disconnect my account?](/help/how-do-i-disconnect-my-account).

*Last updated: April 14, 2026*

Question 29

How do I create a scoped Apify API token for ApifyForge?

Accepted Answer

## Step-by-step

**Step 1:** Open [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations) in a new tab and sign in to Apify.

**Step 2:** Click **Create new token**. Name it `apifyforge-dashboard` so you can identify it later in audit logs.

**Step 3:** Toggle **Limit token permissions** on. **This is the critical step** — without it you will create a full-access token that can do anything to your account. When you toggle it on, Apify reveals three permission dropdowns: Actors, Tasks, and Storages.

**Step 4:** Open the **Actors** dropdown and check exactly these three boxes:

- ✅ **Read** — list your actors and read metadata
- ✅ **Run** — trigger actor runs on your account
- ✅ **List runs** — read run history for analytics

Leave the rest (Build, List webhooks, Manage runs, Manage webhooks) unchecked.

**Step 5:** Leave the **Tasks** dropdown completely empty. ApifyForge does not use Apify Tasks.

**Step 6:** Open the **Storages** dropdown and check exactly these two boxes:

- ✅ **Read** — read dataset results returned by actor runs
- ✅ **Write** — let the token write to storages when making API calls

Leave Create unchecked.

**Step 7:** Scroll down to the **Running Actors** section. This controls what the backend actors ApifyForge triggers can do while they run on your account. Two settings need attention:

- Make sure **Restricted access** is selected (not Full access). This should be the default once Limit token permissions is on.
- Enable the **Allow this token to access default run storages** toggle.

**Why this toggle matters:** the scoped permissions above govern what the token can do via direct API calls, but this toggle governs what code running *inside* an actor started by the token can do with that run's default key-value store and dataset. Without it, the backend actors ApifyForge runs can't write their OUTPUT to their own default KV store — every run crashes at the save step. The toggle is separate from Storages: Write and both are required.

**Step 8:** Click **Save**. Apify displays the token once — it starts with `apify_api_`. Copy it immediately. You cannot retrieve it later; if you lose it, you will have to create a new one.

**Step 9:** Open [ApifyForge Settings → Apify API Token](/dashboard/settings), paste the token, and click Save. You should see a green "connected" indicator within a second or two. If the token is rejected, double-check you copied the full string without a trailing space.

---

## What happens next

Open your ApifyForge dashboard. On a fresh account you will see a **Get Fleet Health Score** button. Click it. ApifyForge triggers the `fleet-analytics` backend actor on your account — the run takes about 2–3 minutes, and you can leave the page while it runs. When it finishes, the hero section re-renders with your Fleet Health Score, Action Plan, cost analysis, and the rest of your analytics.

---

## Security note

Your token is encrypted with **AES-256-GCM** using a server-held key and stored in the ApifyForge PostgreSQL database. The encryption key lives only in the ApifyForge server environment — never in the database, never in logs, never in backups — so even a full database dump would yield ciphertext with no way to decrypt it.

You can revoke access at any time in two places:

1. **In ApifyForge** — Settings → Apify API Token → Delete token. Clears the encrypted value from the database.
2. **In Apify** — [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations), find `apifyforge-dashboard`, click Revoke. This invalidates the token everywhere and takes effect immediately, even if ApifyForge is unreachable. It is the definitive off switch.

For the full security and risk model — including what each permission actually grants, the destructive-capability disclosure on Storages: Write, blast radius if the token leaks, and the production hardening checklist for business-critical accounts — see [What data can ApifyForge access?](/help/what-data-can-apifyforge-access).

---

## Common mistakes

If something is not working, check these first:

- **Forgot to toggle Limit token permissions** — you created a full-access token by accident. Delete it in Apify and create a new one with the toggle on.
- **Forgot to enable "Allow this token to access default run storages"** in the Running Actors section — backend actors triggered by the token can't write their OUTPUT to their own default key-value store, so every run crashes at the save step. This toggle is separate from Storages: Write and both are required. Rotate the token.
- **Missed Storages: Read** — runs succeed but the dashboard shows nothing because the server cannot read the resulting dataset. You burn credits without seeing data. Rotate the token.
- **Missed Storages: Write** — API-level writes fail. Rotate the token.
- **Checked Actors: Build** — not needed. ApifyForge never triggers builds. Read-only build metadata is already granted by Actors: Read.
- **Checked anything under Tasks** — not needed. ApifyForge does not use Apify Tasks at all. Leave the entire Tasks section empty.
- **Token was copied with a trailing space or newline** — ApifyForge rejects it with a 401 when it validates against `/v2/users/me`. Re-copy cleanly.
- **Reused your main full-access token** — defeats the purpose of scoped permissions. Always create a dedicated token named `apifyforge-dashboard`.

---

## Frequently asked questions

### Can I use my existing full-access token instead?

Technically yes, but you shouldn't. A full-access token can modify, delete, or rewrite anything in your Apify account — if it leaks, the attacker has full control. A scoped token with only the five permissions above limits the blast radius to "can read storages and trigger runs," which is dramatically less dangerous. Creating a scoped token takes 2 minutes and is worth the peace of mind.

### What if I accidentally grant too many permissions?

Apify does not let you edit a token's permissions after creation — the scope is locked at create time. Delete the token in Apify, create a new one with the correct scope, and paste that into ApifyForge Settings. The new token automatically overwrites the old one; you do not need to delete the old one from ApifyForge first.

### Does the token expire?

Not unless you set an expiration. As a best practice, rotate every 90 days for regular accounts and every 30 days for business-critical production accounts. Create a new scoped token, paste it into Settings, then revoke the old one in Apify. Full rotation guidance is in [What data can ApifyForge access? → Production hardening](/help/what-data-can-apifyforge-access#production-hardening).

### Can I use the CLI instead of pasting a token into the browser?

Yes. Run `npx apifyforge run <tool>` in your terminal with `APIFY_TOKEN` set in your local environment. The CLI uses your token locally, calls the Apify API directly, and uploads only the computed analytics to your dashboard — nothing is stored on ApifyForge's servers. Both the browser flow and the CLI flow produce identical results in the dashboard. The CLI is the recommended option if your Apify account contains highly sensitive data.

---

## Learn more

- [What data can ApifyForge access?](/help/what-data-can-apifyforge-access) — **the full security reference.** What each permission grants, how the blast radius is bounded, the destructive-capability disclosure on Storages: Write, the scoped-vs-full-access comparison, GDPR guidance, decision framing for high-stakes accounts, and the production hardening checklist.
- [Do you store my API token?](/help/do-you-store-my-api-token) — how the token is encrypted at rest and what revocation actually does on both the ApifyForge and Apify side.
- [How do I connect my Apify account?](/help/how-do-i-connect-my-apify-account) — the broader OAuth sign-in + token setup flow for new users.
- [How do I disconnect my account?](/help/how-do-i-disconnect-my-account) — how to revoke ApifyForge's access cleanly when you're done.

---

*Last updated: April 14, 2026*

Question 30

How do I disconnect my account?

Accepted Answer

Disconnecting from ApifyForge depends on which connection flow you used. If you connected via the browser token flow (paste a scoped token into Settings), there is a stored token to delete. If you used the CLI flow instead (`npx apifyforge run <tool>`), there is no stored token — only a local CLI session on your machine. Either way, the cleanest revocation path is to revoke the token in Apify itself, because that works regardless of which flow you used and takes effect immediately.

## If you used the browser token flow

This is the common case. You have a scoped Apify API token AES-256-GCM-encrypted in the ApifyForge PostgreSQL database. To fully disconnect:

1. **Delete the token in ApifyForge** — open Settings → Apify API Token and click Delete token. This clears the `encrypted_token` column from your user row and prevents ApifyForge from running anything on your Apify account going forward. Any in-flight runs complete, but new runs fail with a 'no token configured' error and the dashboard reverts to the ConnectTokenStep state.
2. **Revoke the token in Apify** — open [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations), find the token you created (the suggested name was `apifyforge-dashboard`), and click Revoke. This invalidates the token on Apify's side, so even if the encrypted copy somehow leaked, it would be useless. **Always do this step.** It is the definitive off switch.
3. **(Optional) Sign out of the dashboard** — click Sign Out in Settings. This ends your OAuth session with GitHub or Google. Your dashboard account remains on the ApifyForge side but has no active session.

The order matters only slightly: revoking in Apify first guarantees the token is dead everywhere even if ApifyForge is unreachable, which is the safer default.

## If you used the CLI flow

If you chose to keep your token entirely on your own machine via the CLI, there is no stored token on the ApifyForge server to delete. To disconnect:

1. **Clear the CLI session** — run `apifyforge logout` in your terminal. This removes the cached dashboard session credentials from your local configuration so the CLI can no longer upload results.
2. **Remove the token from your local environment** — delete the `APIFY_TOKEN` entry from your `.env` file or unset the environment variable. This is managed by you, not by ApifyForge.
3. **(Recommended) Revoke the token in Apify** — at [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations). Even though the token never left your machine, revoking it in Apify is still the cleanest way to make sure it cannot be reused.
4. **(Optional) Sign out of the dashboard** — same as above.

## What gets cleared, and what doesn't

When you disconnect, the following happens on the ApifyForge side:

- Your encrypted token (if any) is deleted from the database.
- Your cached analytics data — revenue figures, failure rates, Fleet Health Score, Action Plan, week-over-week trends — is cleared from the ApifyForge cache.
- Your dashboard resets to the initial empty state (ConnectTokenStep).

Your Apify account itself is completely unaffected — disconnecting from ApifyForge has zero impact on your actors, runs, datasets, schedules, or anything else on the Apify platform. If you had a budget alarm set in Apify, it remains in place. If you had webhooks set up on your actors, they remain in place (ApifyForge never touched them).

Your ApifyForge dashboard account itself (your GitHub/Google OAuth link) remains unless you explicitly delete it. There is no self-serve account deletion yet; if you want to fully wipe your ApifyForge user row, contact support.

## Reconnecting later

Reconnecting is straightforward. Sign back in with GitHub or Google, go to Settings → Apify API Token, paste a fresh scoped token (follow the [create-apify-api-token walkthrough](/help/create-apify-api-token) again), and click Save. Your dashboard repopulates as soon as you click the Run Fleet Analysis button. No previous cached data is restored — everything is pulled fresh. There is no penalty for disconnecting and reconnecting; you get a clean start every time.

For more on the security model and why we store the encrypted token at all, see [Do you store my API token?](/help/do-you-store-my-api-token).

*Last updated: April 14, 2026*

Question 31

What does the Revenue dashboard show?

Accepted Answer

The Revenue dashboard shows PPE earnings across your entire actor portfolio with per-actor breakdown and trend lines. It is powered by the Revenue Tracker actor ($0.40 per sync) and the Cost Watchdog actor ($0.25 per check).

When you click Run Revenue Sync, ApifyForge runs the Revenue Tracker actor on your Apify account. It pulls PPE revenue data for every actor in your portfolio, calculates per-actor earnings, identifies your top performers, and shows trend lines so you can see which actors are growing and which are declining. The Cost Watchdog section shows compute spending — what you pay Apify for platform credits — alongside your revenue so you can see your net position.

Key metrics include total PPE revenue, revenue per actor, revenue trend (growing/declining/stable), compute costs, and revenue-to-cost ratio. The dashboard caches results so you can view your last revenue report without paying again. Most developers run a revenue sync weekly or after significant changes to their portfolio.

For strategies on maximizing revenue, see the related questions about how much you can earn with Apify actors and how to get more users. Visit the Learn section at apifyforge.com/learn/monetization for detailed monetization guides.

Question 32

What does the Health dashboard show?

Accepted Answer

The Health dashboard monitors actor failure rates, success trends, and deprecation signals across your fleet. It is powered by two actors: the Health Monitor ($0.25 per check) and the Deprecation Monitor ($0.25 per scan).

The Health Monitor checks every actor in your account and reports: overall fleet health as a percentage, per-actor success rates with color-coded status (healthy above 99%, warning 90-99%, critical below 90%), failed run counts with trend indicators, and specific recommendations for actors with issues. The Deprecation Monitor scans for actors approaching maintenance flags — stale builds, declining success rates, schema violations — and warns you before Apify's automated system flags them.

Actors are sorted by failure rate so the most critical issues appear first. Each actor row shows a success rate bar, failed/total run counts, status badge, trend indicator, and actionable recommendations. This view replaces manually checking 50+ actors in the Apify Console one at a time.

Run a health check whenever you suspect issues, or schedule weekly checks to catch problems before they trigger maintenance flags. For debugging specific failures, see the related questions about what happens when an actor fails and how to debug failed runs.

Question 33

What does the Quality dashboard show?

Accepted Answer

The Quality dashboard scores your actors on the factors that affect Apify Store visibility and rank. It is powered by the Quality Monitor actor ($0.15 per actor scanned).

Quality Monitor evaluates every actor in your account across 8 weighted dimensions: reliability (25%), documentation (20%), pricing (15%), schema and structure (10%), SEO and discoverability (10%), trustworthiness (8%), ease of use (7%), and agentic readiness (5%). Each dimension returns a 0–100 score with a transparent per-check trace so you can see exactly what passed and what failed.

The dashboard surfaces four qualityGates booleans at a glance — storeReady, agentReady, monetizationReady, schemaReady — that collapse the 8 dimensions into operational readiness questions. For every low-scoring actor, you get a numbered fixSequence showing the top repair steps in order, each with time-to-fix and expected point lift. When you schedule Quality Monitor, it also tracks deltas between runs and fires threshold-crossing alerts only when something regresses — no noise on persistently-bad actors. Deprecation-risk signals flag actors that look abandoned (ancient builds, zero users, deprecation keywords in README).

The quality score directly affects how high your actors appear in Apify Store search. A score of 90+ puts you on page one. Below 70 means your actor is effectively invisible. The dashboard shows exactly which factors to fix for the biggest ranking improvement.

To compare two actors head-to-head on identical input, use the separate A/B Tester tool at /dashboard/tools/ab-tester ($0.15 per test) — it runs each actor N times, aggregates duration / cost / result count, and emits a structured winner verdict with fairness checks.

To turn a one-off scan into ongoing monitoring, set an Alert threshold (1–100) — actors scoring below it count toward the Alert card and become the focus of the next run — and paste a Slack, Discord, or Zapier webhook URL so grade downgrades and threshold crossings ping the channel without anyone needing to refresh the dashboard. Two optional add-ons deepen the scan: "Include deep SEO audit" runs the 11-check Store-SEO analysis per actor (free, adds a few seconds), and "Include LLM output optimization" scores worst-performing actors for token-savings opportunities in their output (extra API cost per actor analyzed).

For strategies on improving your Store ranking, see the related questions about getting more users for your actor and why actors get flagged for maintenance. Visit apifyforge.com/learn/store-seo for the full SEO optimization guide.

## Scan options

Click **Options ▸** in the toolbar to expand the scan configuration panel.

![Quality Monitor run form](/images/marketing/quality/quality-monitor-run-form.jpg)

- **Alert threshold (0–100)** — flag actors below this score and drive the Alert count card. Leave at 0 to score without flagging.
- **Alert webhook URL** (optional) — Slack/Discord/Zapier webhook. Fires on grade downgrades, dimension drops, or actors crossing the alert threshold. Leave empty to score without alerting.
- **Include deep SEO audit** (checkbox) — adds an 11-check Store-SEO analysis per actor. Free and adds a few seconds to the run.
- **Include LLM output optimization** (checkbox) — analyzes worst-scoring actors for token savings in LLM output. Adds an extra API cost per actor analyzed.

Question 34

What does the Failures dashboard show?

Accepted Answer

The Failures dashboard tracks which actors gained new failures since your last check. It is powered by the Failure Tracker actor ($0.10 per report).

Unlike the Health dashboard which shows 30-day aggregate success rates, the Failures dashboard answers a specific question: what broke since yesterday? It works by taking snapshots of every actor's public run statistics (which include all users' runs, not just yours) and comparing them between runs. The first run creates a baseline. Every run after that shows the delta — exactly which actors gained new FAILED, ABORTED, or TIMED-OUT runs.

This solves a real problem: the Apify Console shows a daily bar chart with total failures, but it does not tell you which actors failed. The Apify API does not expose individual runs by other users on your actors. The Failure Tracker works around this limitation by diffing the 30-day aggregate stats, which do include all users.

The dashboard shows four key metrics: new failures since last snapshot, actors affected, new runs since last snapshot, and healthy actors with zero new failures. Below that, each affected actor is listed with color-coded badges showing how many failures, aborts, and timeouts it gained, plus its 30-day success rate for context.

For best results, run the Failure Tracker daily. You can also configure a webhook URL in the input to receive Slack or Discord alerts when failures are detected. For diagnosing specific failures, use the Health dashboard which provides per-actor recommendations. For preventing failures, see the related questions about what happens when actors fail and how to debug failed runs.

Question 35

What are Bulk Operations?

Accepted Answer

Bulk Operations let you update metadata, pricing, categories, or trigger builds across multiple actors in a single action. This is the fleet-management feature that makes ApifyForge essential for developers with 10+ actors.

Without bulk operations, updating the description on 30 actors means opening 30 actor pages in the Apify Console, editing the field, and saving — a process that takes hours. With ApifyForge, you select the actors, enter the new values, and apply the change across all of them in seconds.

Common bulk operations include: updating categories when Apify adds new options (like when MCP_TOOLS was introduced), adjusting PPE pricing across a category of actors, setting consistent SEO metadata (seoTitle, seoDescription) across your fleet, updating Dockerfile base images when Apify releases new versions, and triggering rebuilds after dependency updates.

Bulk operations include a preview mode that shows what would change before applying. This is especially important for pricing changes, which trigger Apify's 14-day notice period for increases. Always preview before applying bulk pricing changes.

For strategies on managing large actor portfolios, visit apifyforge.com/learn/managing-multiple-actors.

Question 36

What are Alerts?

Accepted Answer

Alerts notify you when important events happen across your actor fleet — failures, revenue milestones, new users, cost spikes, and maintenance flags — so you know what happened without checking the dashboard.

ApifyForge can send alerts for several event types. Failure alerts trigger when an actor's success rate drops below a threshold you set (default: 90%). Revenue alerts notify you of significant changes — a daily revenue spike or drop of more than 20% compared to the previous period. Maintenance alerts fire when Apify flags any of your actors for maintenance. Cost alerts trigger when your daily compute spending exceeds a threshold. New user alerts notify you when a new user runs one of your actors for the first time.

Alerts help you catch problems before they compound. A failure alert on Monday means you fix the issue before the success rate drops enough to trigger a maintenance flag on Thursday. A revenue drop alert means you investigate immediately rather than discovering the problem at the end of the month.

Configure alerts in the Alerts page under the Operations section of the dashboard sidebar. You can set thresholds per alert type and choose your notification channel. For proactive monitoring strategies, see the related questions about what happens when actors fail and why actors get flagged for maintenance.

Question 37

How to monitor Apify actor failures, including customer-triggered PPE runs

Accepted Answer

**TL;DR:** ApifyForge Monitor sends instant email and Slack alerts when any Apify actor run fails, times out, or is aborted — including customer-triggered PPE runs. One line of code, zero Apify credits, under 30 seconds from failure to alert.

ApifyForge Monitor is a run-level failure alerting service for Apify actors. It sends email and Slack alerts within seconds when any monitored actor run fails, times out, or aborts — including runs triggered by paying PPE customers. It complements Apify's [built-in monitoring](https://docs.apify.com/platform/monitoring), which provides aggregate charts and threshold alerts for your own runs, by adding per-run alerting for customer-triggered failures.

Setup takes under 5 minutes. Starter tier covers 3 actors, $9/month for 25, $29/month unlimited. No API token sharing required. According to a [2023 PagerDuty survey](https://www.pagerduty.com/resources/reports/digital-operations/), mean time to detect (MTTD) for production incidents averages 4.2 hours without real-time alerting — ApifyForge Monitor reduces this to under 30 seconds for Apify actor failures.

## Questions this page answers

- How do I get alerts when an Apify actor run fails?
- Can I monitor customer-triggered PPE runs?
- What is the difference between static and ad-hoc webhooks?
- Does ApifyForge Monitor replace Apify monitoring or Sentry?
- Do I need to share my Apify API token?
- How do I set up failure monitoring in JavaScript and Python?

## Key definitions

- **Apify actor** — A cloud program that runs on the [Apify platform](https://docs.apify.com/platform/actors), typically used for web scraping, data extraction, or automation.
- **PPE (pay-per-event)** — A pricing model where customers pay per result delivered, not per compute minute. When a PPE customer's run fails, they get no results and the developer may not know.
- **Static webhook** — A webhook configured in the Apify Console UI. Fires only for the actor owner's own runs.
- **Ad-hoc webhook** — A webhook created at runtime inside the actor code using `Actor.addWebhook()`. Fires for every user's runs, including customer-triggered runs.

## Why Apify developers miss customer failures

Apify provides [built-in monitoring](https://docs.apify.com/platform/monitoring) with aggregate charts, threshold alerts, and status notifications for runs you start yourself. This covers your own testing and development runs well. However, when a paying PPE customer triggers a run that fails, times out, or is aborted, the failure appears only in aggregate 30-day statistics — not as an individual alert to the actor owner.

Without per-run alerting for customer-triggered failures, developers typically discover problems through support tickets or negative Store reviews, often days after the failure occurred. ApifyForge Monitor closes this gap by using ad-hoc webhooks to surface every failure from every user in real time.

## Quick comparison: ApifyForge Monitor vs alternatives

| Need | Best option |
|------|-------------|
| Aggregate charts and threshold alerts for your own runs | [Apify built-in monitoring](https://docs.apify.com/platform/monitoring) |
| Per-run alerts for customer-triggered PPE failures | ApifyForge Monitor |
| Full application traces and exception observability | [Sentry](https://sentry.io) or similar APM |
| All three combined | Use all three — they are complementary |

## How it works

ApifyForge Monitor uses Apify's [ad-hoc webhook](https://docs.apify.com/platform/integrations/webhooks/ad-hoc-webhooks) mechanism. You add one line of code — `Actor.addWebhook()` — inside your actor's main function. This registers a webhook on every run, including customer-triggered runs. When a run ends with a FAILED, TIMED_OUT, or ABORTED status, Apify sends the event to ApifyForge, which delivers an alert with the actor name, error message, run ID, and console link.

The key difference from [static webhooks](https://docs.apify.com/platform/integrations/webhooks) configured in the Apify Console: static webhooks fire only for the actor owner's runs. Ad-hoc webhooks created with `Actor.addWebhook()` fire for every user's runs, which is how ApifyForge Monitor surfaces customer-triggered failures.

## Static webhooks vs ad-hoc webhooks for monitoring

Apify supports two webhook types. [Static webhooks](https://docs.apify.com/platform/integrations/webhooks) are configured in the Apify Console and fire only for the actor owner's runs. [Ad-hoc webhooks](https://docs.apify.com/platform/integrations/webhooks/ad-hoc-webhooks) are created at runtime using `Actor.addWebhook()` and fire for every user's runs. ApifyForge Monitor uses ad-hoc webhooks because they are the mechanism that enables customer-run failure visibility.

## Quick setup (under 5 minutes)

**Step 1:** Sign in to ApifyForge Monitor at [apifyforge.com/connect](/connect) — no credit card required for the Starter tier.

**Step 2:** Add an `Actor.addWebhook()` call inside your actor's main function for ACTOR.RUN.FAILED, ACTOR.RUN.TIMED_OUT, and ACTOR.RUN.ABORTED events.

```
await Actor.addWebhook({
  eventTypes: ['ACTOR.RUN.FAILED', 'ACTOR.RUN.TIMED_OUT', 'ACTOR.RUN.ABORTED'],
  requestUrl: 'https://apifyforge.com/api/webhooks/apify-failures',
  idempotencyKey: `apifyforge-${Actor.getEnv().actorRunId}`,
});
```

The `idempotencyKey` prevents duplicate webhooks if the actor restarts mid-run (see [Apify ad-hoc webhook docs](https://docs.apify.com/platform/integrations/webhooks/ad-hoc-webhooks)).

For Python actors:

```
await Actor.add_webhook(
    event_types=['ACTOR.RUN.FAILED', 'ACTOR.RUN.TIMED_OUT', 'ACTOR.RUN.ABORTED'],
    request_url='https://apifyforge.com/api/webhooks/apify-failures',
    idempotency_key=f'apifyforge-{Actor.config.actor_run_id}',
)
```

**Step 3:** Deploy your actor and trigger a test failure to verify alerts are working. Monitoring is now live for every run.

For the full setup guide with production patterns and testing instructions, see [Setup Guide](/monitor/setup-guide).

## Plans and pricing

| Plan | Price | Actors | Alerts |
|------|-------|--------|--------|
| Starter | $0/month | 3 | Email — actor name, status, error, run ID, duration |
| Developer | $9/month | 25 | Email + Slack — adds exit code diagnostics, SUCCEEDED monitoring |
| Pro | $29/month | Unlimited | All of Developer — adds customer user ID, custom integrations |

All plans include custom error context via `Actor.setStatusMessage()`. See [full pricing details](/monitor).

## What it does and does not do

ApifyForge Monitor sends real-time per-run alerts for failure events. It does not validate data quality, detect HTML changes, or replace general APM tools like Sentry. For a detailed comparison of ApifyForge Monitor, Apify's built-in monitoring, and Sentry, see [ApifyForge Monitor vs Apify Monitoring](/monitor/vs-apify-monitoring).

## Troubleshooting: not receiving alerts

If you set up ApifyForge Monitor but are not receiving emails, check these items:

1. Monitoring is enabled (toggle switch is on in the dashboard).
2. Notification email is set and saved.
3. The failing actor's ID is in your monitored actors list (exact match required).
4. Webhook URL on the Apify side matches your current ApifyForge URL.
5. Webhook event types include ACTOR.RUN.FAILED, ACTOR.RUN.TIMED_OUT, and ACTOR.RUN.ABORTED.
6. Check spam/junk folders.
7. Test manually: trigger a known failure and check your failure log.

The most common cause is a mismatch between the actor ID in your monitored list and the `actId` field Apify sends in webhook payloads.

## Learn more

- [Full setup guide (JS + Python)](/monitor/setup-guide) — production patterns, idempotency, testing
- [Customer-run failure alerts explained](/monitor/customer-run-failures) — why customer PPE failures are easy to miss
- [ApifyForge Monitor vs Apify monitoring](/monitor/vs-apify-monitoring) — detailed comparison
- [Slack alerts setup](/monitor/slack-alerts) — connect Slack for failure notifications
- [Exit codes explained](/monitor/exit-codes) — what codes 91, 137, 143, 255 mean

## Frequently asked questions

### Does ApifyForge Monitor require my Apify API token?

No. ApifyForge Monitor uses Apify's webhook system. Apify sends failure events to your ApifyForge webhook URL. No API token sharing needed.

### How fast are alerts delivered?

ApifyForge processes webhooks and sends alerts within 10 seconds. End-to-end latency from failure to inbox is typically under 30 seconds.

### What failure types does it detect?

ApifyForge Monitor tracks 3 failure events: FAILED (exception or crash), TIMED_OUT (exceeded timeout), and ABORTED (manually stopped or platform-killed). Developer and Pro plans also support SUCCEEDED events for SLA tracking.

### Can I track which customer triggered a failure?

Yes, on the Pro plan. Each alert includes the Apify user ID of whoever started the run.

### What is the difference between static and ad-hoc webhooks for monitoring?

Static webhooks are configured in the Apify Console and fire only for the actor owner's runs. Ad-hoc webhooks are created at runtime using `Actor.addWebhook()` and fire for every user's runs, including customer-triggered PPE runs. ApifyForge Monitor uses ad-hoc webhooks because they are the mechanism that enables customer-run failure visibility.

### What happens if my actor restarts mid-run?

Use an `idempotencyKey` based on the run ID (e.g., `apifyforge-${Actor.getEnv().actorRunId}`) to prevent duplicate webhook registrations. If the actor restarts and re-registers the webhook with the same idempotency key, Apify deduplicates it automatically. See the [Apify ad-hoc webhook docs](https://docs.apify.com/platform/integrations/webhooks/ad-hoc-webhooks) for details.

*Last updated: March 30, 2026*

Question 38

What does the Schema Validator do?

Accepted Answer

The Output Guard checks your actor's actual dataset output against the schema you declared in your dataset_schema.json file, catching mismatches before they trigger maintenance flags on the Apify Store. It is one of the most important pre-deploy tools available to Apify developers because schema violations are the number one cause of actors being flagged for maintenance, which directly reduces your Store visibility and revenue.

Here is what the Output Guard checks for. Empty schemas — if your dataset_schema.json exists but defines no fields, the validator flags it immediately. Type mismatches — if your schema declares a field as a string but your actor outputs a number or array for that field, you get a detailed error showing the exact JSON path, the expected type, and the actual type. Undeclared fields — if your actor outputs fields that are not declared in your schema, these are flagged because they can cause issues for users who rely on the schema for data pipeline integration. Missing required fields — if your schema marks fields as required but your actor sometimes omits them, the validator catches this inconsistency.

The validation process works by comparing a sample of your actor's actual output data against the declared schema, field by field and type by type. The output report lists every violation with enough detail to fix it immediately: the field path (e.g., results[0].price.currency), what the schema expected (string), and what the actor actually produced (null). This makes fixing schema issues straightforward rather than requiring you to manually diff JSON structures.

The Output Guard runs as a hosted actor on Apify and costs $0.35 per validation. You point it at your actor by ID, supply a sample Test Input (JSON), and pick a Mode. Validate (one-off) runs the target once and emits a single PASS/FAIL report with every type mismatch, undeclared field, and missing-required violation called out by exact JSON path. Monitor (recurring + drift) is the mode you reach for once an actor is in production — it runs on a schedule, tracks the field baseline across runs, and fires Slack/Discord/Zapier webhook alerts the moment your actor's output drifts (a field disappears, a type flips, null rates jump). After an intentional schema change, tick "Approve this run as the reference baseline" to roll the snapshot forward so future runs do not alarm on the new shape. For related tools, see the questions about the Deploy Guard and Regression Tests, which provide additional pre-deploy validation. Visit apifyforge.com/tools/schema-validator for the full documentation and usage examples.

## Options

![Output Guard run form](/images/marketing/schema-validator/schema-validator-run-form.jpg)

- **Actor ID** (text) — your actor in `username/slug` form, or the raw actor ID. The validator pulls schema from this actor's latest build.
- **Test Input (JSON)** — the input the validator passes to your actor on a sample run. Defaults to `{}` for actors with no required fields.
- **Mode** — `Validate (one-off)` runs once and reports type mismatches, undeclared fields, and missing required fields. `Monitor (recurring + drift)` tracks the field baseline across runs and fires webhook alerts when output drifts.
- **Alert Webhook URL** (Monitor mode only) — Slack/Discord/Zapier webhook. Auto-detects Slack and Discord formats. Leave empty to collect drift data without alerting.
- **Approve this run as the reference baseline** — saves the current output as the "known good" snapshot future runs compare against. Use after intentional schema changes.

Question 39

What is the Test Runner?

Accepted Answer

The Deploy Guard is a testing tool that runs your Apify actor with predefined test inputs and automatically validates the output against assertions you define, giving you confidence that your actor works correctly before you deploy it to the Apify Store.

Each test case in the Deploy Guard consists of three parts: input parameters that define what to feed your actor, output assertions that define what you expect to get back, and optional metadata like test name and timeout. Input parameters can be any valid JSON that matches your actor's input schema — for example, a specific search query, a list of URLs, or configuration options. Output assertions let you specify expected minimum result counts (e.g., at least 10 results), required fields that must be present in every output item (e.g., every result must have a title, url, and price), field type constraints (e.g., price must be a number, not a string), and value range checks.

Here is a practical example. Say you have a Google Maps scraper. You might define three test cases: one that searches for 'coffee shops in London' and expects at least 5 results with name, address, and rating fields; one that searches for a specific place by URL and expects exactly 1 result with all detail fields populated; and one that uses an empty search to verify your actor handles edge cases gracefully without crashing.

The Deploy Guard runs as a hosted actor on Apify and costs $0.35 per suite. You point it at the target actor and pick a Preset — Canary runs a single fast test for sub-10-second pre-push confidence; deeper presets cover the wider set of input shapes you need before deploy. Custom Test Cases run alongside the preset and let you assert minimum result counts, required fields, type constraints, value ranges, and per-test duration ceilings. Both presets and custom cases are billed because each one starts a real run of your target on the Apify platform — that is the point: catching Docker build problems, missing dependencies, network-level proxy differences, and other things that only show up in production. Turn on baseline drift detection to track the field schema across runs and flag any new fields, missing fields, type changes, or null-rate regressions since the last suite. Defaults run at 300s timeout and 512 MB memory per test, but both are tunable in the Options panel for deep crawls or memory-hungry actors.

Run all your test cases with a single command to get a complete pass/fail report. Integrate it with Regression Tests for automated pre-deploy validation across your entire test suite. For more on testing workflows, see the related questions about Cloud Staging and Regression Tests. Visit apifyforge.com/tools/test-runner for documentation and examples.

## Options

![Deploy Guard run form](/images/marketing/test-runner/test-runner-run-form.jpg)

- **Actor ID** (text) — your actor in `username/slug` form, or the raw actor ID.
- **Preset** — pre-built test profile that runs alongside any custom cases. Choices include `Canary` (single fast test, <10s pre-push confidence) and deeper presets for full pre-deploy coverage. Presets and custom cases are both billed.
- **Custom Test Cases (optional, JSON array)** — array of `{name, input, assertions}` objects. Assertions support `minResults`, `maxDuration`, required fields, type constraints, and value ranges.

### Options ▸ panel

- **Enable baseline drift detection** — tracks field schema across runs; flags new fields, missing fields, type changes, and null-rate regressions.
- **Timeout per test (seconds)** — default 300, range 30–3600. Increase for deep crawls, LLM-heavy runs, or multi-page actors.
- **Memory per test (MB)** — default 512, range 128–8192 (step 128). Match the target actor's real memory use. Higher = faster + more compute.

Question 40

What is Cloud Staging?

Accepted Answer

Cloud Staging runs your actor in Apify's actual production environment before you make it public on the Store, catching issues that local testing cannot detect. Think of it as a staging server specifically designed for Apify actors, integrated directly into your deployment pipeline.

The core problem Cloud Staging solves is the gap between your local development environment and Apify's production infrastructure. When you develop and test locally using the Apify CLI, your actor runs on your machine with your Node.js version, your installed packages, your network configuration, and your file system. When the same actor runs on Apify's cloud platform, it runs inside a Docker container with potentially different dependency versions, different network routing, different proxy configurations, and different memory and CPU constraints. Cloud Staging bridges this gap by running your actor in the real environment before users see it.

Here is what Cloud Staging validates. Docker build success — your Dockerfile actually builds without errors on Apify's infrastructure. Dependency resolution — all your npm or pip packages install correctly in the container environment. Schema compliance — your actor's actual output matches your declared dataset_schema.json when running in production. Success rate — your actor completes without crashing on Apify's infrastructure. Output quality — the results your actor produces in the cloud match the quality and completeness you see locally. Network behavior — your actor can reach its target websites from Apify's IP ranges and through its proxy infrastructure.

The staging process is straightforward. You push your code to Apify, then trigger a Cloud Staging run through ApifyForge. The tool runs your actor with your test inputs in the production environment and reports back on every validation check. The whole process typically takes a few minutes and costs one or two PPE events — usually under $0.01 per staging run.

Cloud Staging is most valuable when combined with the Output Guard and Deploy Guard as a three-layer testing approach: validate schema locally (free), run test cases locally (free), then verify everything works in production with Cloud Staging (minimal cost). For more on this testing workflow, see the related questions about the Output Guard, Deploy Guard, and Regression Tests. Visit apifyforge.com/tools/cloud-staging for setup instructions.

Question 41

What are Regression Tests?

Accepted Answer

Regression tests are automated test suites that run before every publish to verify that new code changes have not broken existing functionality in your Apify actors. They are your safety net against deploying breaking changes that cause failures, empty outputs, or maintenance flags on the Store.

The concept is simple but powerful. For each actor, you define multiple test cases that cover different input combinations, edge cases, and expected behaviors. When you push new code, the regression suite runs every test case and reports any failures. If a test that was passing before now fails, you have a regression — something in your new code broke previously working functionality. The suite catches this before the broken code reaches production and your users.

Here are the types of regressions these tests catch that simple smoke tests miss. Broken pagination — your actor used to return 100 results but now returns only 10 because a pagination handler broke. Changed field names — a refactor renamed 'productPrice' to 'price' but your schema and downstream integrations expected the old name. New anti-bot measures — the target website added Cloudflare protection and your actor no longer gets past the landing page. Rate limit changes — the target API reduced its rate limit and your actor now gets throttled, returning partial results. Dependency updates — a new version of Cheerio or Playwright changed an API method signature, causing silent failures.

To set up regression tests, define your test cases in the ApifyForge Deploy Guard with specific inputs and expected output assertions. Then integrate the regression suite with your Git workflow by adding a pre-push hook that runs all test cases before allowing a push to proceed. If any test fails, the push is blocked and you see exactly which test case failed and why. This prevents broken code from ever reaching your Apify builds.

The ApifyForge Deploy Guard stores your regression test history, so you can track when specific tests started failing, correlate failures with code changes, and identify patterns over time. This historical data is invaluable for debugging intermittent failures. For related testing tools, see the questions about the Deploy Guard, Output Guard, and Cloud Staging. Visit apifyforge.com/tools/regression-tests for setup guides and best practices.

Question 42

How do I validate my actor's output schema?

Accepted Answer

Use the ApifyForge Output Guard to compare your actor's actual dataset output against the schema declared in your dataset_schema.json file. The validator runs as a hosted actor on Apify ($0.35 per validation), starts a fresh test run of your target with the input you supply, and catches the exact issues that trigger maintenance flags on the Apify Store — usually in well under a minute.

Here is the step-by-step process to validate your schema. First, make sure your actor has a dataset_schema.json file in its root directory. This file declares the structure and types of every field your actor outputs. If you do not have one yet, create it based on your actor's actual output structure — every field your actor produces should be declared with its correct type (string, number, boolean, array, object). Second, push the actor to Apify so the validator can call it. Third, open apifyforge.com/tools/schema-validator, paste in your actor ID, supply a Test Input JSON, choose Validate (one-off) for a single PASS/FAIL run or Monitor (recurring + drift) to track the field baseline over time, and hit Run Validation.

The validator performs four categories of checks. Type mismatches — if your schema says a field is a string but your actor outputs a number, you get an error with the exact JSON path (e.g., results[0].price), the expected type (string), and the actual type (number). Undeclared fields — if your actor outputs fields not listed in your schema, these are flagged because they indicate your schema is incomplete. Missing required fields — if your schema marks a field as required but it is absent from some output items, the validator catches this. Empty schemas — if your dataset_schema.json exists but defines no fields, this is immediately flagged as invalid.

Schema violations matter because they directly affect your actor's visibility on the Apify Store. When Apify's automated quality checks detect schema mismatches over a period of several days, your actor gets flagged with a maintenance warning. This reduces its ranking in Store search results and category pages, which means fewer users find and run your actor, which means less PPE revenue. The damage from a maintenance flag can take weeks to recover from even after the underlying issue is fixed.

The prevention strategy is simple: run the Output Guard before every release, then leave Monitor mode running on production actors so any drift fires a webhook alert before Apify's automated quality checks notice. For a complete testing workflow, combine the Output Guard with the Deploy Guard and Cloud Staging for three layers of pre-deploy validation. See the related questions about the Output Guard tool and Regression Tests for more details. Visit apifyforge.com/tools/schema-validator for full documentation.

Question 43

What is the Compliance Scanner?

Accepted Answer

The Compliance Scanner assesses legal and regulatory risk for any Apify actor before you scrape. It analyzes the actor's metadata — name, description, categories, and README — to detect PII collection indicators, Terms of Service exposure against 13 major platforms, and applicable regulations across 6 jurisdictions.

The scan checks three risk categories. PII risk scans for 18 keywords that indicate personal data collection: email, phone, name, address, salary, resume, identity, and more. ToS risk matches against known platform policies: LinkedIn and Facebook are HIGH risk (active litigation), Amazon and Google are MEDIUM, Reddit and Yelp are LOW. Authentication risk flags actors accessing content behind login walls, relevant to CFAA compliance.

The scan produces an overall risk level (LOW/MEDIUM/HIGH), lists applicable regulations (GDPR, CCPA, CFAA, CAN-SPAM, PIPEDA, ePrivacy Directive), and provides actionable recommendations like 'document your lawful basis for processing personal data under GDPR' or 'add opt-out mechanism for email collection.'

Run it on a single actor by ID, or tick "Scan my entire fleet instead" to audit every actor in your Apify account in one go — useful before a portfolio compliance review or a Store quality push. Strict mode raises sensitivity when metadata is sparse or wording is ambiguous; reach for it on enterprise reviews. The scan covers four dimensions by default — README + documentation, input/dataset schemas, agentic readiness, and change signals (drift versus the previous scan) — each an independent toggle so you can drop one to shorten the run and remove it from the scorecard.

Compliance Scanner costs $0.15 per scan and does NOT run the target actor — it reads metadata only. Visit apifyforge.com/tools/compliance-scanner for documentation.

## Options

![Compliance Scanner run form](/images/marketing/compliance-scanner/compliance-scanner-run-form.jpg)

- **Actor ID** (text) — single actor to audit, in `username/slug` form.
- **Scan my entire fleet instead** (checkbox) — audits every actor in your account in a single run. Use for portfolio-wide compliance review.

### Options ▸ panel

- **Strict mode** — raises sensitivity when metadata is sparse or wording is ambiguous. Use for enterprise/compliance-heavy review.
- **Max actors to scan** (fleet mode only) — default 250, max 1000. Reduce for a faster initial pass.
- **Scan scope** — four toggles, all on by default. Turn off to shorten the run and drop the dimension from the scorecard:
  - **README + documentation** — required sections, legal disclosures, responsible-use
  - **Input + dataset schemas** — existence, field-level descriptions
  - **Agentic readiness** — MCP/agent-consumer friendliness, structured output
  - **Change signals (drift)** — compare against the previous scan, flag regressions

Question 44

What is the Cost Calculator?

Accepted Answer

The Cost Calculator estimates what any actor will cost at various volumes before you spend credits. Enter an actor ID and get a breakdown of PPE pricing, average compute cost per run, average events per run, and volume projections from 1x to 100x.

The calculator fetches the actor's current PPE configuration and analyzes the last 20 successful runs for real compute costs — duration, memory, and platform charges. Projections separate PPE charges from compute charges so you see exactly where your money goes. This is especially valuable when comparing competing actors: two scrapers might both extract the same data, but one costs 3x more at high volume.

Cost Calculator costs $0.20 per calculation and does not run the target actor. Visit apifyforge.com/tools/cost-calculator for documentation.

Question 45

What is the Input Tester?

Accepted Answer

The Input Guard validates your input JSON against an actor's declared input schema without running the actor. It checks required fields, type constraints (string vs number vs integer), enum values, and numeric ranges. If your input is invalid, you get specific error messages before wasting credits on a failed run.

Beyond validation, the Input Guard generates ready-to-use API call snippets: cURL, Python (apify-client), and JavaScript (apify-client). Paste the generated code directly into your integration instead of hand-crafting API calls.

Single Input mode validates one JSON object. Batch mode accepts an array of `{label, input}` pairs so you can verify a whole set of integration shapes in one run — handy for configuration matrices or for migrating off another scraper. Strictness controls how warnings affect the verdict: Lenient (warnings never downgrade a pass), Standard (default), or Strict (any warning fails). Leave "Include schema quality audit" on to also score the target actor's input schema for documentation, agent-readiness, and completeness — you get one report covering both your input and their schema.

Input Guard costs $0.15 per validation and does not run the target actor. Visit apifyforge.com/tools/input-tester for documentation.

## Options

![Input Guard run form](/images/marketing/input-tester/input-tester-run-form.jpg)

- **Actor ID** (text) — the actor whose input schema you want to validate against.
- **Test Input** — `Single input` accepts one JSON object; `Batch` accepts an array of `{label, input}` pairs to validate many inputs at once.
- **Strictness** — `Lenient` (warnings never downgrade a pass), `Standard` (default), `Strict` (any warning fails the decision).

### Options ▸ panel

- **Include schema quality audit** — audits the target actor's input schema for documentation, agent-readiness, and completeness. Default on.

Question 46

What is the LLM Output Optimizer?

Accepted Answer

The LLM Output Optimizer analyzes actor output and recommends how to reduce token consumption when feeding data to large language models. It scores every field by information density — high-value fields like name, url, and email are kept, while low-value fields like raw HTML, internal IDs, and timestamps are flagged for removal.

The optimizer reads sample output from the actor's most recent successful run and produces a field-by-field analysis with token counts, value classifications, and recommended actions (keep, drop, or truncate). It generates an optimized schema and reports expected token savings — typically 40-70%.

LLM Output Optimizer costs $0.35 per analysis. It does not run the target actor — it reads from the latest dataset. Visit apifyforge.com/tools/llm-optimizer for documentation.

Question 47

What is the Pipeline Builder?

Accepted Answer

The Pipeline Preflight validates multi-actor data pipelines and generates TypeScript orchestration code. Define pipeline stages with actor IDs and field mappings, and the builder checks that output fields from each stage map correctly to the next stage's input fields.

The builder identifies type mismatches between stages, warns about missing field mappings, and generates complete Actor.call() chain code that you can deploy as a new orchestration actor. It also estimates total pipeline cost by summing PPE prices across all stages.

The generated code shape is yours to pick. Codegen mode controls how production-ready the output is: Minimal emits a plain Actor.call chain, Production-ish wraps each stage in try/catch with log.warning, and Typed adds explicit ApifyCallOptions and `satisfies` assertions for end-to-end TypeScript safety. Pagination mode picks the dataset-read strategy: Limit 1000 is fast but silently truncates anything past 1K records, while Paginate all iterates until the cursor is exhausted — what you want as soon as a stage emits more than 1K. Tick "Validate runtime" to call the Input Guard on each stage with synthetic input from the mapping; it catches broken fieldMappings before codegen at a per-stage Input Guard charge. By default the builder also emits a top-level `agentContract` object describing the pipeline for MCP/LLM planners — turn it off in the Options panel if you are integrating with a non-agent runtime.

Pipeline Preflight costs $0.40 per build and does not run any actors — it reads schemas from latest builds. Visit apifyforge.com/tools/pipeline-builder for documentation.

## Options

![Pipeline Preflight run form](/images/marketing/pipeline-builder/pipeline-builder-run-form.jpg)

- **Pipeline Stages (JSON)** — array of stage objects. Each stage requires `actorId`; downstream stages can declare a `fieldMapping` mapping their input fields to the previous stage's output fields.
- **Codegen mode** — `Minimal` (plain `Actor.call` chain), `Production-ish` (try/catch + log.warning per stage), `Typed` (adds explicit `ApifyCallOptions` + `satisfies` assertions).
- **Pagination mode** — `Limit 1000` (fast, silently truncates past 1K records) or `Paginate all` (generated helper iterates until offset + count ≥ total). Stages emitting >1000 records silently lose data with `limit_1000`.
- **Validate runtime** — calls input-tester on each stage with synthetic input from the mapping. Catches broken `fieldMapping`s before codegen. Adds a per-stage input-tester charge.

### Options ▸ panel

- **Suggestion mode** — controls how `NO_FIELD_MAPPING` issues suggest fix candidates. `Schema only` (default) or `Schema + naming`.
- **Strictness** — `Default` or `Strict` (louder advisory surface).
- **Emit agent contract** — emits a top-level `agentContract` object for MCP/LLM planners. Default on.

Question 48

What is the A/B Tester?

Accepted Answer

The A/B Tester runs two actors against the same input and emits a structured winner verdict with fairness checks. It is built for the call you have to make often: "these two actors look like they solve the same problem — which one should I actually run?". The tool runs each actor N times in parallel, aggregates duration, cost, result count, and field coverage, then reports a winner with confidence and fairness gates so you can ship the result without second-guessing.

Use the A/B Tester when you are evaluating a competitor against your own actor before publishing, choosing between two third-party actors that scrape the same site, validating that a refactor of your actor produces the same output as the previous version, or verifying that a new pricing tier still wins on cost-per-result.

## How the verdict works

Each test runs the same input through both actors N times (configurable via Mode). The tool computes success rate, median duration, p90 duration, median cost, cost per result, median result count, and field coverage. The winner is decided by a configurable Decision Profile, and the verdict includes confidence (low/medium/high), winner consistency across pairwise matchups, and fairness gates (reliability, separation, variance, sample, fairness — each marked PASS or FAIL).

If the actors return substantially different output shapes, the verdict is downgraded to `monitor` with a `RESULT_SHAPE_DIVERGENCE` warning — the tool refuses to declare a winner when the actors are not actually solving the same problem.

## Options

![A/B Tester run form](/images/marketing/ab-tester/ab-tester-run-form.jpg)

- **Actor A / Actor B** (ID or name) — the two actors to compare. Both receive the same Test Input.
- **Test Input (JSON)** — identical input passed to both actors. Must be valid JSON compatible with both schemas.
- **Mode** — runs per actor: `Smoke` (1 run — compatibility check only, capped at monitor readiness), `Standard` (3 runs — routine comparison), `Decision` (5 runs — production switching), `High stakes` (10 runs — needs to survive scrutiny).
- **Decision profile** — weighting for the winner score: `Balanced` (default), `Speed-first`, `Cost-first`, `Output-first` (result count + coverage), `Reliability-first`. Always reported in the output for auditability.
- **Compare to last comparable run** (checkbox) — looks up the previous run for this same pair + input + mode + profile and reports deltas. Turn on to track whether the comparison is moving over time.

### Options ▸ panel

- **Runs override** — 0 = use mode default. 1–10 overrides the runs-per-actor count.
- **Timeout (sec)** — default 300, range 30–3600. Per-run wait.
- **Memory (MB)** — default 512, range 128–8192 (step 128). Per-run allocation.
- **Include Apify Store context** — attaches each actor's monthly users, star rating, and categories to the verdict. Default on.

## Pricing

The A/B Tester costs $0.15 per test run. The two target actors each consume their own PPE for each of the N runs. For a Standard (3-run) test against an actor priced at $0.05/result that returns 5 results, the actor cost is `2 actors × 3 runs × 5 results × $0.05 = $1.50`, plus the $0.15 A/B Tester fee. Visit apifyforge.com/dashboard/tools/ab-tester to run a comparison.

Question 49

What is the Release Gate?

Accepted Answer

The ApifyForge Release Gate is a CI/CD pre-release validation tool that runs 9 automated checks on your Apify actors before every deploy, at a cost of $0.42 per actor. It replicates the 4 exact checks the Apify Store runs daily — effective input validation, run success, non-empty dataset, and duration under 300 seconds — and adds 5 extended data quality checks the Store does not perform: schema conformance, field completeness, golden baseline comparison, log anomaly detection, and performance regression tracking. If your actor would fail the Store's automated tests and receive a [maintenance flag](/glossary/maintenance-flag), the Release Gate catches it before you push.

## The 9 checks explained

The checks are split into two groups: 4 Store-equivalent hard gates and 5 extended data quality checks.

**Store-equivalent checks (A through D):**

1. **Check A — Effective Input Validation:** Parses your actor's [input schema](/glossary/input-schema), builds the effective test input from prefill and default values the same way the Store does, and verifies all required fields are satisfied.
2. **Check B — Run Succeeded:** Starts your actor via the Apify API with the effective input and verifies it reaches SUCCEEDED status.
3. **Check C — Non-Empty Dataset:** Verifies the default [dataset](/glossary/dataset) contains at least one item.
4. **Check D — Duration Under 300s:** Verifies the run completes within the Store's 5-minute (300-second) window.

**Extended data quality checks (E through I):**

5. **Check E — Schema Conformance:** Validates output items against expected field types, catching type drift (e.g., a price field changing from number to string).
6. **Check F — Field Completeness:** Enforces per-field null and empty rate thresholds — if your email field is suddenly null in 80% of items, this check fails.
7. **Check G — Golden Baseline Comparison:** Compares current output against a pinned golden dataset, detecting schema drift (added or removed fields), count drift, and value changes.
8. **Check H — Log Pattern Detection:** Scans run logs for 13 known-bad patterns including CAPTCHA, 429 rate limits, TypeError, ReferenceError, blocked, login required, ECONNREFUSED, and socket hang up.
9. **Check I — Performance Regression:** Warns if run duration exceeds 2x the baseline, catching performance regressions even when the actor still finishes under 5 minutes.

## Operating modes

The Release Gate supports 4 operating modes:

1. **Gate mode:** Runs all checks and fails if any ERROR-severity check fails — this is what you use in CI/CD pipelines.
2. **Dry Run mode:** Runs all checks but never fails, producing a report you can review without blocking deploys.
3. **Approve Baseline mode:** Runs checks and saves the current output as the new golden baseline for future comparisons.
4. **Bootstrap Baseline mode:** Same as Approve but intended for first-time setup when no prior baseline exists.

Three profiles control which checks run. **Store Default** runs checks A through D only — exactly what the Apify Store tests. **Extended** runs all 9 checks. **Custom** lets you configure checks per test case.

## Best for

- Developers who publish actors to the [Apify Store](/glossary/apify-store) and need to prevent [maintenance flags](/glossary/maintenance-flag)
- Teams managing portfolios of 10 to 100+ actors who need fleet-wide pre-release validation
- CI/CD pipelines using GitHub Actions that need automated go/no-go gating
- Catching silent data quality regressions that pass the Store's basic checks but degrade output

## Not ideal for

- One-time actor runs that are not published to the Store (maintenance flags only apply to Store-listed actors)
- Actors that intentionally produce empty datasets (Check C will fail)
- Free-tier Apify accounts with limited monthly credits — each gate run costs $0.42 per actor plus the target actor's own [PPE](/glossary/ppe) cost

## Portfolio gating

The Release Gate validates 1 to 100+ actors in a single run with configurable concurrency. It processes targets in parallel using a semaphore pattern, respects PPE spending limits, and can stop on the first failure if configured. For a portfolio of 50 actors, a full gate run costs $21.00 and completes in under 10 minutes — compared to 12-25 hours of manual pre-release testing at 15-30 minutes per actor.

## Golden baseline management

Golden baselines use a named key-value store called `release-gate-baselines` with a `BASELINES.json` manifest that maps each actor, test case, and channel to an immutable [dataset](/glossary/dataset) snapshot. Baselines are never updated automatically in gate mode — you must explicitly approve new baselines, following the pytest-regressions "fail with diff, approve to update" pattern.

## Output and CI/CD integration

The Release Gate outputs a structured `REPORT.json` to the run's default key-value store, making it consumable by GitHub Actions workflows. The report includes per-target, per-test-case, per-check results with evidence strings, plus optional artifacts like sample items, log tails, and golden diffs. The same report is also pushed to the dataset for viewing in the Apify Console.

For GitHub Actions integration, trigger the ApifyForge Release Gate after pushing an [actor build](/glossary/actor-build). The gate starts a test run of the exact build you pushed, validates all checks, and the GitHub Actions step fails if the gate fails. The `REPORT.json` can be fetched from the run's key-value store and written to GitHub's job summary for PR-level visibility.

## Pricing

The ApifyForge Release Gate costs **$0.42 per target actor** checked. This covers the gate logic only — you also pay standard PPE for the target actor's test run. A typical development cycle using the [Output Guard](/help/what-does-the-schema-validator-do) ($0.35), [Deploy Guard](/help/what-is-the-test-runner) ($0.35), and Release Gate ($0.42) costs about $1.12 total. Apify's free tier includes $5/month in credits, which covers approximately 11 full gate runs.

## Frequently asked questions

### How does the Release Gate differ from the Apify Store's automated tests?

The Apify Store runs 4 checks (input validation, run success, non-empty dataset, duration under 300s) on your actors periodically. The ApifyForge Release Gate replicates those same 4 checks and adds 5 more: schema conformance, field completeness, golden baseline comparison, log anomaly detection, and performance regression tracking. The Store checks reactively — after your actor is already published. The Release Gate checks proactively — before you deploy.

### Can I use the Release Gate to prevent maintenance flags?

Yes. The Release Gate's Store Default profile runs the exact same 4 checks the Store uses to decide whether to flag an actor for maintenance. If your actor passes the Release Gate in Store Default mode, it will pass the Store's automated tests. Running the gate before every deploy is the most reliable way to prevent maintenance flags, which reduce your actor's Store search ranking and visibility.

### How do golden baselines work?

A golden baseline is a snapshot of your actor's "known good" output — a specific dataset captured at a point when the output was correct. On subsequent gate runs, Check G compares the current output against this baseline and flags differences: new fields added, fields removed, item count changes, or value drift. You approve new baselines explicitly using Approve Baseline mode after verifying the changes are intentional.

### What happens if a check fails in gate mode?

The gate run completes all checks but reports an overall FAILED status. The structured `REPORT.json` lists every check result with evidence strings explaining exactly what failed and why. In a GitHub Actions pipeline, the step exits with a non-zero code, blocking the deploy. You fix the issue, push again, and re-run the gate.

### How long does a gate run take?

A single-actor gate run typically completes in 1-3 minutes, depending on how long the target actor takes to run. Portfolio runs of 50 actors with concurrency of 5 complete in under 10 minutes. The Release Gate itself adds minimal overhead — most of the time is spent waiting for the target actor's test run to finish.

### Can I run the Release Gate locally?

The Release Gate runs as an Apify actor on your account, so it requires an active Apify API token and internet access. It cannot run fully offline. However, for local pre-push checks, the ApifyForge [Output Guard](/help/what-does-the-schema-validator-do) and [Deploy Guard](/help/what-is-the-test-runner) both support local execution at zero cost.

*Last updated: March 28, 2026*

Question 50

Do the tools cost anything?

Accepted Answer

Every tool in ApifyForge runs as an Apify actor on your account and charges a small PPE fee per use. Results are cached in your dashboard, so viewing previous reports is always free.

Here is the complete pricing by category:

Testing: Output Guard ($0.35), Deploy Guard ($0.35/suite), Cloud Staging ($0.50), Regression Suite ($0.35/suite).

Schema & Data: Input Guard ($0.15), Schema Registry ($0.20), Schema Diff ($0.20), LLM Output Optimizer ($0.35).

Cost & Planning: Cost Calculator ($0.20), Plan Advisor ($0.25), Proxy Analyzer ($0.25).

Compliance: Compliance Scanner ($0.15).

Pipeline: Pipeline Preflight ($0.40).

Privacy: Personal Data Exposure Report ($1.00).

Analytics: Fleet ($0.40), Revenue ($0.40), Health ($0.25), Quality ($0.25), Cost Watchdog ($0.25), Completeness ($0.25), Deprecation ($0.25), A/B Tester ($0.15).

A typical development cycle — schema validation, test suite, and cloud staging — costs about $1.20 total. Visit apifyforge.com/pricing for the full breakdown.

Question 51

What is the Personal Data Exposure Report?

Accepted Answer

The Personal Data Exposure Report scans 20+ data broker and people-search sites to find where your personal information is listed online. It searches sites like Spokeo, WhitePages, TruePeopleSearch, Radaris, and others, plus checks the DataBreach.com breach database and uses Brave Search to find broker listings indexed by search engines.

For each site where your data is found, the report provides a direct link to your listing (when available), what types of data are exposed (name, address, phone, email, relatives, etc.), step-by-step removal instructions specific to that site, a link to the opt-out page, what you will need to complete the removal (email, phone number, profile URL), and an estimated time to complete the removal process.

The report also generates an overall exposure score from 0 to 100, categorises removals by difficulty (easy, medium, hard), and identifies PeopleConnect family sites where one removal covers multiple brokers — Intelius, ZabaSearch, Instant Checkmate, AnyWho, and Addresses.com can all be removed with a single submission at suppression.peopleconnect.us.

The actor costs $1.00 per report and typically completes in under 10 seconds. For comparison, Incogni charges $7.49/month ($89.88/year) and DeleteMe charges $10.75/month ($129/year). Running a monthly exposure scan costs $12/year.

The report does not submit removal requests on your behalf — it provides the detection and a personalised removal guide. You follow the step-by-step instructions to remove your data from each site.

To use it, enter your first name, last name, and optionally your state and email address. Adding an email enables breach database checks. Visit apifyforge.com/tools/exposure-report to run a report.

Question 52

What happens when an actor fails?

Accepted Answer

When an Apify actor fails, the run terminates with a FAILED status and the platform records the error details, exit code, and run log. Understanding why actors fail — and how to diagnose failures quickly — is critical for maintaining high success rates and avoiding maintenance flags that reduce your Store visibility.

The most common failure categories are: runtime errors (unhandled exceptions in your code), timeouts (actor exceeds its configured timeout or the default 3600 seconds), out-of-memory crashes (actor tries to use more RAM than allocated), network errors (target website is down or blocks requests), and input validation failures (user provides invalid or missing required inputs). Each category produces different error signatures in the run log.

When a failure occurs, here is what happens on the platform side. The run status is set to FAILED. The error message and stack trace are captured in the run log. If the actor was mid-way through producing results, any data already pushed to the dataset is preserved — you do not lose partial results. The user who triggered the run is charged only for the compute time actually consumed, not the full expected duration. If the failure happened before any meaningful work, the charge is minimal.

For actor developers, failures directly impact your quality score and Store visibility. Apify tracks your actor's success rate over the past 7 days. If the rate drops below a threshold (typically around 80%), your actor may receive a maintenance flag. This is why catching failures before they reach production — using the ApifyForge Deploy Guard, Output Guard, and Cloud Staging — is so valuable. A single automated test that costs $0.001 can prevent a failure that costs you weeks of reduced Store visibility.

ApifyForge monitors failure rates across your entire fleet through the dashboard. You can see which actors are failing most frequently, identify patterns in failure types, and prioritize fixes based on revenue impact. For step-by-step debugging instructions, see the related question about how to debug a failed actor run. For testing tools that prevent failures, see the questions about the Deploy Guard and Cloud Staging.

Question 53

How do I debug a failed Apify actor run?

Accepted Answer

Start with the run log in the Apify Console — it contains the error message, stack trace, and timeline of what happened during the run. Navigate to your actor, click the failed run, and read the log from the bottom up to find the error that caused the failure.

Here is a systematic debugging process. Step one: identify the error type from the run log. Look for these common patterns. An unhandled exception shows a JavaScript Error with a stack trace pointing to the exact file and line number — this is usually the easiest to fix because the location is explicit. A timeout error means the actor exceeded its time limit, which could indicate infinite loops, slow network requests, or the target website rate-limiting your requests. An out-of-memory error means the actor tried to use more RAM than its allocated memory (check the actor.json memory setting). A network error like ECONNREFUSED, ETIMEDOUT, or HTTP 403/429 means the target website is unreachable or blocking your requests.

Step two: reproduce the failure locally. Copy the exact input from the failed run (available in the run details), run the actor locally with apify run, and observe whether the same error occurs. If it reproduces locally, you can debug with standard Node.js debugging tools — console.log, the Node.js debugger, or VS Code's built-in debugger. If it does not reproduce locally, the issue is likely environment-specific (different Node.js version, Docker configuration, proxy behavior, or network routing). Use Cloud Staging to test in the production environment.

Step three: check for common causes specific to each error type. For timeouts — add progress logging to identify where the actor gets stuck, reduce the scope of work per run, implement request queuing with configurable concurrency. For out-of-memory — reduce batch sizes, stream data instead of loading everything into memory, increase the memory allocation in actor.json. For 403/429 blocking — add or upgrade proxies, reduce request rate, add random delays, switch from Cheerio to Playwright for JavaScript-heavy sites.

For fleet-wide debugging, the ApifyForge dashboard shows failure trends across all your actors, helping you identify whether failures are isolated incidents or systemic issues (like a proxy provider outage or a target website redesign). For prevention strategies, see the related questions about the Deploy Guard, Output Guard, and what happens when an actor fails.

Question 54

Why is my Apify actor under maintenance?

Accepted Answer

An Apify actor enters maintenance when the platform's automated quality system detects repeated failures over a multi-day window. According to [Apify's maintenance policy](https://docs.apify.com/platform/actors/running/maintenance), 2 failed auto-tests within 3 days triggers the maintenance flag, and 28 more days without a fix leads to deprecation. ApifyForge tracks these quality signals across your entire fleet so you can catch declining health before a flag appears.

## The 4 most common causes

Apify's quality checks evaluate four areas. Here are the triggers ranked by how often they cause maintenance flags, based on patterns observed across actors managed through [ApifyForge](https://apifyforge.com):

1. **Dataset schema mismatch** — Your actor's actual output does not match the declared `dataset_schema.json`. This is the most common cause and the hardest to spot manually because the actor runs successfully while silently producing non-conformant data. The [ApifyForge Output Guard](https://apifyforge.com/tools/schema-validator) catches these mismatches locally in under 2 seconds before you push.
2. **Low success rate** — Your 7-day rolling success rate drops below approximately 80%. Even 3-4 failures in a week on a low-volume actor can cross this threshold. The [ApifyForge dashboard](https://apifyforge.com) displays per-actor success rates updated after every run.
3. **Crash on default input** — Apify periodically runs your actor with its default input configuration. If that run throws an unhandled exception, times out, or exits with a non-zero code, it counts as a failed auto-test.
4. **Stale build** — Actors that have not been rebuilt in 90+ days may receive a staleness flag, particularly if they depend on deprecated Node.js base images or outdated Crawlee versions.

## How to diagnose the specific trigger

**Step 1:** Check the Apify Console for automated run results — navigate to your actor, filter runs by "System" origin, and look for recent failures. These auto-test runs happen every 1-3 days.

**Step 2:** Run the [ApifyForge Output Guard](https://apifyforge.com/tools/schema-validator) against your actor to check for schema mismatches. Validation takes under 2 seconds and catches the #1 cause of maintenance flags.

**Step 3:** Check your 7-day success rate in the [ApifyForge dashboard](https://apifyforge.com). A rate below 80% is a strong indicator the flag was triggered by cumulative failures rather than a single event.

**Step 4:** Review your build age. If your last build is older than 90 days, push a fresh build even if no code has changed — this resets the staleness clock and rebuilds against current base images.

## How to resolve a maintenance flag

Resolving a maintenance flag requires fixing the root cause and then demonstrating consistent operation over several days:

**Step 1:** Identify the cause using the diagnostic steps above.

**Step 2:** Fix the issue — update your dataset schema, handle the failing edge case, increase timeout limits, or rebuild with current dependencies.

**Step 3:** Push a new build to Apify using `apify push`.

**Step 4:** Run your actor successfully with the default input at least 3-5 times over 2-3 days to rebuild your rolling success rate above 80%.

**Step 5:** Wait for Apify's periodic re-evaluation. The maintenance flag does not clear instantly — it typically takes 3-7 days of consistent clean runs before the system removes it.

## Prevention checklist

Preventing maintenance flags is significantly more effective than resolving them after they appear. A single maintenance flag can reduce your Apify Store visibility for 1-2 weeks even after resolution, directly impacting [PPE revenue](https://apifyforge.com/glossary/ppe). Use this checklist before every push:

- Run the [ApifyForge Output Guard](https://apifyforge.com/tools/schema-validator) to verify output matches `dataset_schema.json`
- Run the [ApifyForge Deploy Guard](https://apifyforge.com/tools/test-runner) with default input to confirm the actor completes successfully
- Use [Cloud Staging](https://apifyforge.com/tools/cloud-staging) to test in the production environment — local runs may behave differently due to proxy routing, Docker configuration, or Node.js version differences
- Monitor fleet health in the [ApifyForge dashboard](https://apifyforge.com) to catch declining success rates before they cross the 80% threshold
- Rebuild actors at least once every 60 days to avoid staleness flags

For a deeper explanation of maintenance flags, see the [ApifyForge glossary entry on maintenance flags](https://apifyforge.com/glossary/maintenance-flag). For testing strategies, see the [actor testing guide](https://apifyforge.com/learn/actor-testing). For debugging failed runs that contribute to maintenance flags, see the related help article on [how to debug a failed Apify actor run](https://apifyforge.com/help/how-do-i-debug-a-failed-apify-actor-run).

## Frequently asked questions

### How long does it take for a maintenance flag to clear?

Apify re-evaluates actor health every 1-3 days. After fixing the underlying issue and running 3-5 successful auto-tests, the maintenance flag typically clears within 3-7 days. During this period, your actor remains usable but may appear lower in Apify Store search results.

### Does a maintenance flag affect my PPE revenue?

Yes. Actors with a maintenance flag receive reduced visibility in the Apify Store, which means fewer users discover and run them. According to Apify's ranking algorithm, quality score — which includes maintenance status — directly influences Store placement. Lower placement leads to fewer runs and lower [Pay Per Event revenue](https://apifyforge.com/glossary/ppe).

### Can I prevent maintenance flags automatically?

ApifyForge provides automated monitoring that alerts you when an actor's success rate drops below configurable thresholds. The [Deploy Guard](https://apifyforge.com/tools/test-runner) can run regression tests across your fleet on a schedule, catching failures before Apify's auto-test system does. Combined with the [Output Guard](https://apifyforge.com/tools/schema-validator) in your CI pipeline, these tools eliminate the most common maintenance flag triggers.

### What is the difference between maintenance and deprecation?

Maintenance is a warning state — your actor still works and users can run it, but its Store visibility is reduced. Deprecation is permanent removal from the Apify Store. According to Apify's policy, an actor that remains in maintenance for 28 consecutive days without a fix is deprecated. Once deprecated, the actor must be re-submitted through the Store review process to be relisted.

### My actor works locally but fails Apify's auto-test — why?

Environment differences between local and cloud runs are common. The top causes are: different Node.js versions (Apify uses the version specified in your Dockerfile base image), different proxy routing (local runs use your IP while cloud runs use Apify's datacenter proxies), Docker memory limits (the default is 256 MB unless you specify more in actor.json), and network timeouts (cloud runs may have different DNS resolution or firewall rules). Use [ApifyForge Cloud Staging](https://apifyforge.com/tools/cloud-staging) to test in the exact production environment.

*Last updated: March 27, 2026*

Question 55

How do I handle Apify actor timeouts?

Accepted Answer

Actor timeouts occur when your actor exceeds its configured time limit (set in actor.json, default is 3600 seconds / 1 hour). The fix depends on whether the timeout is caused by the actor doing too much work, getting stuck on slow operations, or encountering infinite loops.

Here is how to diagnose and fix each cause. Too much work per run — if your actor tries to process thousands of pages or API calls in a single run, it may legitimately need more time. Solutions: increase the timeout in actor.json (up to 86400 seconds / 24 hours for paid plans), implement pagination in your actor input so users can process data in smaller batches, or add request queuing with configurable concurrency (maxConcurrency in Crawlee) to process requests in parallel rather than sequentially. Stuck on slow operations — if your actor hangs on specific network requests, implement request-level timeouts using AbortController or the timeout option in fetch/axios. A common pattern is setting a 30-second timeout per individual request so that a single slow target does not stall the entire run. For Crawlee-based actors, set navigationTimeoutSecs and requestHandlerTimeoutSecs in the crawler configuration. Infinite loops — these are bugs where your actor enters a cycle it never exits, such as continuously re-crawling the same URL or retrying a permanently failing request. Add logging at key decision points so you can see the actor's progress in the run log and identify where it gets stuck.

For Crawlee-based scrapers, the most effective timeout prevention measures are: set maxRequestsPerCrawl to cap the total number of pages processed, set maxRequestRetries to limit retries on failing URLs (default is 3, which is usually fine), and implement a progress callback that logs completion percentage so you can monitor whether the actor is making forward progress.

From a fleet management perspective, ApifyForge tracks timeout rates across your actors in the dashboard. If you see a spike in timeouts, it often indicates an external change — the target website became slower, added more anti-bot measures, or restructured its pages. For related debugging advice, see the questions about debugging failed runs and what happens when an actor fails.

Question 56

Can I use Apify with Python?

Accepted Answer

Yes, Apify has a full Python SDK available on PyPI (package name: apify) that supports complete actor development, API access, dataset management, and all the same capabilities as the JavaScript SDK. Python is a first-class citizen on the Apify platform.

Here is how Python development on Apify works. Install the SDK with pip install apify. Create a new actor project using the Apify CLI with apify create my-actor --template python, which generates a project scaffold with the correct Dockerfile, requirements.txt, and main.py structure. Your actor code uses the same Actor.main() async pattern as the JavaScript SDK — you define an async main function that receives the actor context, reads input, does its work, and pushes results to the dataset.

Python actors run inside Docker containers on Apify's infrastructure, using official Apify Python base images that come pre-configured with the SDK and common dependencies. Your Dockerfile extends the base image and installs your additional requirements. The build process handles pip dependency resolution, so you just list your packages in requirements.txt and they are available at runtime.

Python is particularly popular for several categories of actors. Data science and analytics actors that use pandas, numpy, scipy, or scikit-learn for processing scraped data. Machine learning actors that run inference using TensorFlow, PyTorch, or Hugging Face transformers. Natural language processing actors that use spaCy, NLTK, or custom NLP pipelines. API integration actors where Python's requests library and rich ecosystem of API client libraries make integration straightforward. Data transformation actors that leverage Python's excellent CSV, JSON, and database libraries.

For web scraping specifically, Python actors can use BeautifulSoup, Scrapy, or the Apify Python SDK's built-in HTTP client. Browser automation is available through Playwright for Python. While the Crawlee framework (Apify's recommended scraping library) is currently more mature in its JavaScript version, the Python ecosystem provides equivalent capabilities through other libraries.

All ApifyForge tools work seamlessly with Python actors because they interact through the Apify API, which is language-agnostic. The Output Guard, Deploy Guard, Cloud Staging, and fleet analytics do not care whether your actor is written in Python, JavaScript, TypeScript, or any other language. For more on building actors, visit apifyforge.com/glossary/actors. For related topics, see the questions about what happens when an actor fails and how to debug failed runs.

Question 57

How much can I earn with Apify actors?

Accepted Answer

Earnings from Apify actors vary widely depending on your niche, pricing strategy, actor quality, and portfolio size, but individual actors solving high-value problems can earn $100 to $1,000 or more per month, and developers managing portfolios of 20+ actors often generate $2,000 to $10,000 per month in total PPE revenue.

The revenue model works through Pay Per Event (PPE) pricing. You set a price per event for your actor — for example, $0.50 per 1,000 results, $0.01 per page scraped, or $0.10 per search query. Every time a user runs your actor, they pay that per-event price multiplied by the number of events consumed. Apify handles all billing and payment, and you receive your earnings. The key insight is that PPE pricing should reflect the value your actor provides to the user, not just the compute cost. A B2B lead generation actor that saves a sales team hours of manual research can justifiably charge $0.05 per lead even if the compute cost is $0.001.

Here are the factors that determine how much an individual actor earns. Niche selection is the most important factor — actors in B2B lead generation, competitive intelligence, price monitoring, real estate data, and job market analysis command higher prices because the data is directly valuable to businesses. Pricing strategy matters — underpricing leads to high volume but low revenue, while overpricing reduces adoption. Study competing actors in the Store to benchmark your pricing. Quality score directly affects Store visibility — actors with high success rates, complete schemas, and good metadata rank higher in search, which means more users discover and run them. A free tier or low-cost entry point drives initial adoption, which builds usage volume and improves your Store ranking.

To maximize your earnings, consider a portfolio strategy rather than relying on a single actor. Build multiple actors that serve the same niche from different angles — for example, a Google Maps scraper, a Yelp scraper, a TripAdvisor scraper, and a review aggregator all serve the local business intelligence market. Each actor earns independently, and users in that niche often use multiple actors. Developers who build focused portfolios in high-value niches consistently earn more than those who build scattered one-off actors.

ApifyForge helps you optimize revenue with its fleet analytics dashboard, which shows PPE earnings per actor over time, identifies your top performers, flags underperforming actors, and tracks the quality scores that affect Store visibility. Visit apifyforge.com/glossary/ppe for a detailed breakdown of PPE pricing mechanics. For related strategies, see the question about how to get more users for your actor.

Question 58

How do I get more users for my actor?

Accepted Answer

Actor discoverability on the Apify Store is driven by three main factors — quality score, search relevance, and usage volume — and optimizing all three is the key to growing your user base and PPE revenue.

Start with metadata optimization, which is the fastest way to improve discoverability. Your actor title should be keyword-rich, 40-60 characters long, and clearly state what the actor does. For example, 'Google Maps Scraper - Extract Business Data and Reviews' is better than 'Maps Data Tool' because it contains the search terms users actually type. Your description should include secondary keywords and clearly explain the value proposition in the first two sentences. Your README should follow a proven structure: summary paragraph, how it works section, input parameters with examples, output format with sample data, pricing and cost information, and a FAQ section that targets long-tail search queries.

Next, optimize your quality score, which directly affects your ranking in Store search results and category pages. The quality score is a composite metric based on several factors: success rate (aim for 95% or higher), schema compliance (zero mismatches between your output and dataset_schema.json), metadata completeness (title, description, README, categories, SEO fields all filled out), build freshness (regular updates signal an active, maintained actor), and response to maintenance flags (resolve them quickly when they occur). Use the ApifyForge Output Guard before every push and monitor your quality score trends in the ApifyForge dashboard.

Finally, drive initial usage to build momentum. The Apify Store algorithm favors actors with higher usage volume, creating a positive feedback loop — more users lead to higher rankings, which lead to more users. To bootstrap this cycle, share your actor in relevant online communities where your target users spend time (Reddit, Hacker News, industry-specific forums and Slack groups). Write blog posts or tutorials that demonstrate your actor solving a real problem, and link to it in the Apify Store. Offer a free tier or low-cost entry point that lets users try your actor with minimal risk — once they see value, they convert to regular paid usage. Reach out to YouTubers and bloggers who cover web scraping and automation topics.

ApifyForge provides Store analytics that show how your actors rank for specific search terms, which metadata fields are incomplete, and how your quality score compares to competing actors in the same category. Visit apifyforge.com/glossary/store-seo for detailed Store SEO strategies. For related topics, see the questions about what the Apify Store is and how much you can earn with actors.

Question 59

My dashboard shows no data

Accepted Answer

An empty dashboard usually means your API token is invalid, expired, or was not saved correctly. The first step is to go to the ApifyForge Settings page and verify that your token is entered and saved.

Here is a systematic troubleshooting process. Step one: check your token in Settings. If the token field is empty, you need to re-enter it. If it shows a token, try removing it, saving, then re-entering it and saving again. This forces a fresh validation. Step two: if you just connected your account for the first time, wait 3-5 minutes. The initial data population requires pulling your actor list, run history, and analytics from the Apify API, which takes a few minutes depending on how many actors you have. You should see the dashboard begin populating gradually. Step three: verify your token is valid by logging into your Apify account at console.apify.com/account/integrations and checking the token status. If the token has been revoked, expired, or had its permissions changed, it will not work with ApifyForge. Generate a fresh token and enter it in ApifyForge Settings.

Other potential causes include browser-related issues. Try clearing your browser cache and cookies for the ApifyForge domain, then reload the page. Try a different browser or incognito/private browsing mode to rule out browser extension interference. Some ad blockers and privacy extensions block API calls, which can prevent dashboard data from loading.

If you have a brand new Apify account with no actors and no run history, the dashboard will appear empty because there is no data to display. This is expected behavior — the dashboard will populate as you create actors and run them. If you have actors on Apify but they still do not appear in ApifyForge after 10 minutes with a valid token, the issue may be on our end. Check the ApifyForge status page for any ongoing service disruptions.

For persistent issues that none of the above steps resolve, open a bug report at github.com/apifyforge/apifyforge with your browser name and version, a screenshot of the empty dashboard, and confirmation that your token works when tested directly against the Apify API. For related topics, see the questions about how to connect your Apify account and how to disconnect your account.

Question 60

My actor is getting blocked or returning 403 errors

Accepted Answer

HTTP 403 (Forbidden) and 429 (Too Many Requests) errors mean the target website's anti-bot system has detected your scraper and is blocking its requests. This is one of the most common issues in web scraping, and the fix depends on what anti-bot measures the site uses and what your current setup looks like.

Here is a layered approach to resolving blocking issues, starting with the simplest fixes and escalating to more advanced techniques. Layer one — add proxies if you are not using them. Scraping without proxies means all your requests come from a single IP address, which is trivial for websites to detect and block. Datacenter proxies rotate your IP across a pool of addresses and work for most basic websites. Configure proxies in your Crawlee crawler with the proxyConfiguration option. Layer two — upgrade to residential proxies. If you are already using datacenter proxies but still getting blocked, the target site likely checks whether the IP belongs to a datacenter or a residential ISP. Residential proxies route your traffic through real residential IP addresses, which are much harder for anti-bot systems to distinguish from regular users. Sites like Amazon, LinkedIn, Google, Zillow, and most social media platforms require residential proxies. Layer three — switch from CheerioCrawler to PlaywrightCrawler or PuppeteerCrawler. Cheerio makes raw HTTP requests without executing JavaScript, which is fast but does not pass browser fingerprint checks. Modern anti-bot systems like Cloudflare, PerimeterX, and DataDome check for JavaScript execution, browser APIs, canvas fingerprints, and WebGL rendering. PlaywrightCrawler runs a real browser that passes these checks.

Additional techniques to layer on top of proxies and browser crawling include reducing your request rate with the maxRequestsPerMinute Crawlee option (start with 20-30 requests per minute and adjust based on results), adding random delays between requests using the Crawlee autoscaling configuration, rotating User-Agent headers to mimic different browsers, setting realistic viewport sizes and screen resolutions in Playwright, and handling CAPTCHAs with third-party solving services when they appear.

Some particularly aggressive websites require all of these measures simultaneously. If you are still getting blocked after implementing everything above, the target site may be using advanced bot detection that requires session management, cookie handling, or specialized scraping approaches. For related debugging advice, see the questions about how to debug failed actor runs and what happens when an actor fails.

Question 61

An actor shows as 'maintenance' but it works fine

Accepted Answer

This is a common and frustrating situation where your actor runs successfully when you test it manually, but Apify's automated quality system still flags it with a maintenance warning. The explanation is that the maintenance flag is based on automated quality checks that evaluate different criteria than your manual tests, and these checks run independently on Apify's schedule.

Here are the most likely reasons your actor shows as maintenance despite appearing to work fine. Dataset schema mismatch — your actor produces output that does not exactly match the types and fields declared in your dataset_schema.json. Your manual test might work perfectly and return useful data, but if the schema says price is a number and your actor sometimes outputs price as a string like '$19.99' instead of 19.99, the automated check flags this as a violation. This is the most common cause of 'works fine but flagged' situations. Inconsistent output on default input — Apify's quality checks run your actor with its default input. If your default input is configured differently from the input you use for manual testing, the automated runs might fail or produce different output. Make sure your actor works correctly with exactly the default input shown in your input schema. Success rate over time — even if your actor works now, the maintenance flag evaluates success rate over the past 7 days. If your actor had a bad period with multiple failures last week, the flag might still be active even though you have since fixed the issue. The flag clears once enough successful runs accumulate to bring the rolling average above the threshold. Stale builds — if your actor has not been updated in 90+ days, it may be deprioritized regardless of its current functionality.

To diagnose the specific cause, use the ApifyForge Output Guard to check for any schema mismatches you might have missed. Check the quality score breakdown in the ApifyForge dashboard, which shows the individual factors contributing to your overall score. Review the automated run logs in the Apify Console, specifically the runs triggered by Apify's system (not your manual runs) to see if they show different behavior.

To resolve the flag, fix the identified issue, push a new build, run your actor successfully with the default input several times, and wait for Apify's periodic re-evaluation. The flag does not clear instantly — it typically takes several days of clean runs. For more details on the maintenance system, see the related question about why actors get flagged for maintenance.

Question 62

Where do I report bugs?

Accepted Answer

Report bugs by opening an issue on our GitHub repository at github.com/apifyforge/apifyforge. We use GitHub Issues as our primary bug tracking system because it allows public visibility, threaded discussions, and status tracking for every reported issue.

To help us diagnose and fix your bug quickly, include the following information in your report. The error message — copy the exact error text, including any error codes or stack traces. What you were doing — describe the steps that led to the bug, step by step, so we can reproduce it. Which tool or dashboard page was involved — specify whether the issue is in the Output Guard, Deploy Guard, Cloud Staging, fleet dashboard, revenue tracker, quality score page, or another feature. Browser information — include your browser name and version (e.g., Chrome 120, Firefox 115, Safari 17) and your operating system. Screenshots — visual evidence of the bug is extremely helpful, especially for layout issues, incorrect data displays, or error dialogs. Browser console output — if applicable, open your browser's developer tools (F12), go to the Console tab, and copy any error messages shown there.

For tool-specific bugs, include additional details. For Output Guard issues: the actor name, the content of your dataset_schema.json, a sample of your actor's output, and the full validator error output. For Deploy Guard issues: the actor name, the test case configuration you used, and the complete test output including any assertion failures. For Cloud Staging issues: the actor name, the build version tested, and the staging report output. For dashboard and analytics issues: whether the data appears incorrect (and what the correct value should be), whether the page fails to load entirely, or whether specific metrics are missing.

We triage new issues daily and typically respond within 24 hours. Bug priority is based on impact: issues affecting data accuracy (incorrect revenue figures, wrong success rates), tool functionality (validator crashes, test runner failures), and security concerns are addressed first. Feature requests are welcome but tracked separately from bugs.

If your issue is urgent — for example, revenue tracking shows incorrect data that is affecting business decisions — mention 'urgent' in the issue title and we will prioritize it. For general questions that are not bugs, check the other FAQ answers on this page first, as many common questions are already answered. For related information, see the questions about how to connect your account and troubleshooting empty dashboards.

Frequently Asked Questions

About ApifyForge

Pricing & Costs

Choosing the Right Actor

Developer Tools & Features

Technical Questions

All Questions from Help Center