# Cost Watchdog — Spending Monitor & Budget Alerts (`ryanclinton/cost-watchdog`) Actor Actor Cost Watchdog. Available on the Apify Store with pay-per-event pricing. - **URL**: https://apify.com/ryanclinton/cost-watchdog.md - **Developed by:** [ryan clinton](https://apify.com/ryanclinton) (community) - **Categories:** Developer tools, Automation - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $250.00 / 1,000 cost checks This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Cost Watchdog — Apify Spending Monitor & Budget Alerts Monitor your Apify account spending and catch runaway costs before they become surprise bills. Cost Watchdog fetches your recent runs, calculates spending rates, detects cost anomalies, and sends webhook alerts when budgets are exceeded. The #1 complaint from Apify users is unexpected charges — this tool solves that. **Why use this?** A single misconfigured Actor can burn through your entire monthly budget overnight. Cost Watchdog analyzes your last 24 hours of runs in seconds, flags anything unusual, and tells you exactly which Actors are costing the most — before you get the bill. ### How to monitor your Apify spending 1. Go to the [Cost Watchdog](https://apify.com/ryanclinton/cost-watchdog) Actor page on Apify 2. Paste your **Apify API token** (find it at Settings > Integrations) 3. Set your daily and/or monthly budget thresholds 4. Click **Start** and get your spending report in seconds 5. Optionally add a webhook URL to receive alerts automatically That's it. One run gives you a complete spending breakdown with anomaly detection and budget projections. ### Features - **Spending breakdown** — See total spend, cost per hour, and projected daily/monthly costs - **Per-Actor cost profiles** — Know exactly which Actors cost the most and their average cost per run - **Anomaly detection** — Automatically flags runs that cost significantly more than the Actor's average - **Budget alerts** — Set daily and monthly limits, get warned when you're on track to exceed them - **Webhook notifications** — Send alerts to Slack, Discord, or any webhook endpoint - **Cost trend analysis** — See if your spending is increasing, decreasing, or stable - **Run success tracking** — Monitor how many runs succeeded vs failed in the analysis window ### Use cases #### Daily budget monitoring Run Cost Watchdog on a schedule (every hour or every 6 hours) to continuously monitor spending. Set a daily budget of $10 and a webhook URL pointing to your Slack channel. If any Actor starts burning more than expected, you'll know immediately. #### Post-mortem cost analysis Had an unexpected spike on your Apify bill? Run Cost Watchdog with a longer analysis window (168 hours = 1 week) to identify which Actors caused the spike and which specific runs were anomalous. #### Actor cost optimization Use the per-Actor cost profiles to find your most expensive Actors. Compare the average cost per run across Actors to identify which ones need optimization — maybe they're using too much memory, running too long, or making unnecessary requests. #### Team spending governance If your team runs dozens of Actors, set up Cost Watchdog as a scheduled task with budget limits and Slack alerts. Everyone gets visibility into spending without needing Apify Console access. ### Input | Field | Type | Description | Default | |-------|------|-------------|---------| | `apiToken` | String | Your Apify API token (required) | — | | `dailyBudget` | Number | Alert if daily spend exceeds this ($) | — | | `monthlyBudget` | Number | Alert if projected monthly spend exceeds this ($) | — | | `anomalyThreshold` | Number | Alert if a run costs more than Nx the Actor's average | `3` | | `webhookUrl` | String | URL to POST alerts to (Slack, Discord, etc.) | — | | `hoursBack` | Integer | Analysis window in hours (1-720) | `24` | #### Example input ```json { "apiToken": "apify_api_YOUR_TOKEN_HERE", "dailyBudget": 10.00, "monthlyBudget": 200.00, "anomalyThreshold": 3, "webhookUrl": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK", "hoursBack": 24 } ```` ### Output Each run produces one spending report in the dataset: ```json { "type": "spending-report", "period": "last 24 hours", "totalSpend": 4.52, "projectedDailySpend": 4.52, "projectedMonthlySpend": 135.60, "dailyBudget": 10.00, "monthlyBudget": 200.00, "budgetStatus": "OK", "topSpenders": [ { "actor": "ryanclinton/website-contact-scraper", "actorId": "BCq991ez5HObhS5n0", "runs": 45, "totalCost": 2.10, "avgCostPerRun": 0.047 }, { "actor": "ryanclinton/google-maps-email-extractor", "actorId": "abc123def", "runs": 12, "totalCost": 1.80, "avgCostPerRun": 0.15 } ], "anomalies": [ { "actor": "ryanclinton/company-deep-research", "actorId": "2cAY2V9yz1JE2H1S2", "runId": "abc123", "cost": 1.20, "avgCost": 0.15, "multiplier": 8.0, "reason": "Run lasted 45 minutes vs usual 5 minutes" } ], "costTrend": "stable", "alertSent": false, "totalRuns": 57, "successfulRuns": 54, "failedRuns": 3, "checkedAt": "2026-03-18T14:30:00.000Z" } ``` #### Output fields | Field | Type | Description | |-------|------|-------------| | `type` | String | Always `spending-report` | | `period` | String | Human-readable time window analyzed | | `totalSpend` | Number | Total USD spent in the analysis window | | `projectedDailySpend` | Number | Extrapolated 24-hour spending based on current rate | | `projectedMonthlySpend` | Number | Extrapolated 30-day spending based on current rate | | `dailyBudget` | Number/null | Your configured daily budget | | `monthlyBudget` | Number/null | Your configured monthly budget | | `budgetStatus` | String | `OK`, `DAILY_EXCEEDED`, `MONTHLY_PROJECTED_EXCEEDED`, or `BOTH_EXCEEDED` | | `topSpenders` | Array | Top 10 Actors by total cost, with run counts and averages | | `anomalies` | Array | Runs that cost significantly more than their Actor's average | | `costTrend` | String | `stable`, `increasing`, `decreasing`, or `insufficient_data` | | `alertSent` | Boolean | Whether a webhook alert was sent this run | | `totalRuns` | Integer | Total number of runs in the analysis window | | `successfulRuns` | Integer | Runs that completed successfully | | `failedRuns` | Integer | Runs that failed, aborted, or timed out | | `checkedAt` | String | ISO timestamp of when the check was performed | ### How to use the API You can run Cost Watchdog programmatically and integrate it into your monitoring stack. #### Python ```python from apify_client import ApifyClient client = ApifyClient(token="YOUR_API_TOKEN") run = client.actor("ryanclinton/cost-watchdog").call( run_input={ "apiToken": "YOUR_API_TOKEN", "dailyBudget": 10.00, "monthlyBudget": 200.00, "anomalyThreshold": 3, "hoursBack": 24, } ) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"Total spend: ${item['totalSpend']:.2f}") print(f"Budget status: {item['budgetStatus']}") print(f"Anomalies: {len(item['anomalies'])}") for spender in item["topSpenders"][:5]: print(f" {spender['actor']}: ${spender['totalCost']:.4f} ({spender['runs']} runs)") ``` #### JavaScript / Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('ryanclinton/cost-watchdog').call({ apiToken: 'YOUR_API_TOKEN', dailyBudget: 10.00, monthlyBudget: 200.00, anomalyThreshold: 3, hoursBack: 24, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); const report = items[0]; console.log(`Total spend: $${report.totalSpend.toFixed(2)}`); console.log(`Budget status: ${report.budgetStatus}`); console.log(`Anomalies: ${report.anomalies.length}`); report.topSpenders.slice(0, 5).forEach(s => { console.log(` ${s.actor}: $${s.totalCost.toFixed(4)} (${s.runs} runs)`); }); ``` #### cURL ```bash curl -X POST "https://api.apify.com/v2/acts/ryanclinton~cost-watchdog/runs?token=YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "apiToken": "YOUR_API_TOKEN", "dailyBudget": 10.00, "monthlyBudget": 200.00, "hoursBack": 24 }' ``` ### How it works 1. **Fetches recent runs** — Calls the Apify API (`GET /v2/actor-runs`) to retrieve all runs started within the analysis window. Paginates through results automatically. 2. **Calculates per-Actor costs** — Groups runs by Actor ID, sums the `usageTotalUsd` field for each Actor, and computes average cost per run. Resolves Actor IDs to human-readable names. 3. **Detects anomalies** — For each Actor with 2+ runs, compares each run's cost to the Actor's average. Any run costing more than `anomalyThreshold` times the average is flagged with a reason (e.g., "Run lasted 45 minutes vs usual 5 minutes"). 4. **Projects spending** — Calculates cost per hour from the analysis window and extrapolates to daily and monthly projections. 5. **Analyzes cost trend** — Splits the analysis window in half and compares spending in each half. If the second half costs 30%+ more than the first, the trend is "increasing". 6. **Sends alerts** — If budget thresholds are exceeded or anomalies are detected, POSTs a JSON alert to your webhook URL. Compatible with Slack incoming webhooks, Discord webhooks, and custom endpoints. ### Scheduling for continuous monitoring The real power of Cost Watchdog is running it on a schedule. In the Apify Console: 1. Go to **Schedules** and create a new schedule 2. Set it to run every hour (or every 6 hours for lower-cost monitoring) 3. Add a webhook URL to get alerts in Slack or Discord 4. Set your daily and monthly budgets Now you'll be alerted automatically whenever spending goes off-track — no more surprise bills. ### Webhook payload format When an alert is triggered, Cost Watchdog POSTs this JSON to your webhook URL: ```json { "text": "Apify Cost Watchdog Alert\nDaily spending $12.50 exceeds budget $10.00", "alerts": [ "Daily spending $12.50 exceeds budget $10.00" ], "report": { ... full spending report ... } } ``` The `text` field is compatible with Slack and Discord webhook formats. The full `report` object is included for custom integrations. ### Limitations - **Cost data availability** — The `usageTotalUsd` field is populated after a run completes. Currently running Actors won't show their final cost yet. - **API rate limits** — Actor name resolution makes one API call per unique Actor. For accounts with 100+ unique Actors, only the top 20 spenders get named (the rest show Actor IDs). - **Projection accuracy** — Daily and monthly projections assume constant spending. Bursty workloads (e.g., batch jobs that run once per day) will have less accurate projections. - **Historical data** — The Apify API returns up to 1000 runs per page. Accounts with very high run volumes may not capture all runs in larger analysis windows. ### FAQ #### How accurate are the cost projections? Projections are based on linear extrapolation from the analysis window. If you run the same workloads consistently, projections are very accurate. For bursty workloads (e.g., a big batch job once a day), use a 24-hour window to capture a full cycle. #### Will this catch a runaway Actor in real time? Not in real time — Cost Watchdog runs as a batch check. For near-real-time monitoring, schedule it to run every hour. It will catch anomalies within the hour and alert you via webhook. #### What does the anomaly threshold mean? An anomaly threshold of 3 (the default) means: if a single run costs 3x or more than that Actor's average cost per run, it's flagged. Lower the threshold to 2 to catch smaller anomalies, or raise it to 5 for only major spikes. #### Can I use this with a team account? Yes. The API token determines which account's runs are analyzed. Use a team admin token to see all runs across the team. #### Does this work with Pay-Per-Event Actors? Yes. Cost Watchdog reads the `usageTotalUsd` field which includes all costs — compute, storage, and PPE charges. Every run's total cost is captured regardless of pricing model. #### How much does Cost Watchdog itself cost? $0.05 per check. If you run it hourly, that's $1.20/month. A small price to prevent a $50 surprise bill. ### Pricing - **$0.05 per watchdog check** — one check per run - Run it once a day for $1.50/month, or hourly for $36/month - Pays for itself the first time it catches a runaway Actor ### Changelog #### v1.0.0 (2026-03-18) - Initial release - Per-Actor spending breakdown with top 10 spenders - Anomaly detection with configurable threshold - Daily and monthly budget alerts - Webhook notifications (Slack, Discord compatible) - Cost trend analysis (stable, increasing, decreasing) - Run success/failure tracking # Actor input Schema ## `apiToken` (type: `string`): Your Apify API token. Find it at https://console.apify.com/settings/integrations ## `dailyBudget` (type: `number`): Alert if daily spending exceeds this amount in USD. Leave empty to skip daily budget check. ## `monthlyBudget` (type: `number`): Alert if projected monthly spending exceeds this amount in USD. Leave empty to skip monthly budget check. ## `anomalyThreshold` (type: `number`): Alert if a single run costs more than this many times the actor's average cost per run. For example, 3 means a run costing 3x the average triggers an alert. ## `webhookUrl` (type: `string`): URL to POST alert data to when a budget threshold is exceeded or anomaly is detected. Compatible with Slack, Discord, or any webhook endpoint. ## `hoursBack` (type: `integer`): How many hours back to analyze. Default is 24 hours (one full day). ## Actor input object example ```json { "dailyBudget": 5, "monthlyBudget": 50, "anomalyThreshold": 3, "hoursBack": 24 } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "dailyBudget": 5, "monthlyBudget": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("ryanclinton/cost-watchdog").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "dailyBudget": 5, "monthlyBudget": 50, } # Run the Actor and wait for it to finish run = client.actor("ryanclinton/cost-watchdog").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "dailyBudget": 5, "monthlyBudget": 50 }' | apify call ryanclinton/cost-watchdog --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ryanclinton/cost-watchdog", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Cost Watchdog — Spending Monitor & Budget Alerts", "description": "Actor Cost Watchdog. Available on the Apify Store with pay-per-event pricing.", "version": "1.0", "x-build-id": "uTNGYeSo0t9NZZ3ZX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~cost-watchdog/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-cost-watchdog", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ryanclinton~cost-watchdog/runs": { "post": { "operationId": "runs-sync-ryanclinton-cost-watchdog", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ryanclinton~cost-watchdog/run-sync": { "post": { "operationId": "run-sync-ryanclinton-cost-watchdog", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "apiToken" ], "properties": { "apiToken": { "title": "Apify API Token", "type": "string", "description": "Your Apify API token. Find it at https://console.apify.com/settings/integrations" }, "dailyBudget": { "title": "Daily budget ($)", "minimum": 0, "type": "number", "description": "Alert if daily spending exceeds this amount in USD. Leave empty to skip daily budget check." }, "monthlyBudget": { "title": "Monthly budget ($)", "minimum": 0, "type": "number", "description": "Alert if projected monthly spending exceeds this amount in USD. Leave empty to skip monthly budget check." }, "anomalyThreshold": { "title": "Anomaly threshold (multiplier)", "minimum": 1.5, "type": "number", "description": "Alert if a single run costs more than this many times the actor's average cost per run. For example, 3 means a run costing 3x the average triggers an alert.", "default": 3 }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "URL to POST alert data to when a budget threshold is exceeded or anomaly is detected. Compatible with Slack, Discord, or any webhook endpoint." }, "hoursBack": { "title": "Analysis window (hours)", "minimum": 1, "maximum": 720, "type": "integer", "description": "How many hours back to analyze. Default is 24 hours (one full day).", "default": 24 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```