# Apify Actor Monitor (`thenetaji/apify-actor-monitor`) Actor

Monitors your Apify account actor performance. Takes daily snapshots, computes diffs, and delivers an HTML report via email.

- **URL**: https://apify.com/thenetaji/apify-actor-monitor.md
- **Developed by:** [The Netaji](https://apify.com/thenetaji) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## 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

## Apify Actor Monitor

> ⚠️ **First Run Notice**
> On the very first run, no actor comparison report will be generated — there is no previous snapshot to compare against. The actor will collect and store today's baseline snapshot. **The full report with red/yellow/green status, revenue deltas, and trend indicators will appear on the second run onwards.** Schedule a second run after at least an hour or the next day to start seeing meaningful insights.

A self-contained Apify Actor that watches your own Apify account, takes daily snapshots of every actor's performance, and emails you a clean HTML report — no external servers, no database, no third-party email service required.

![alt text](./samples/image.png)

---

### What it does

Every time it runs, the Actor:

1. Pulls analytics for all actors you own (runs, revenue, cost, users, success rate)
2. Compares today's numbers against the previous run's snapshot
3. Tags each actor **red / yellow / green** based on how it's doing
4. Saves the snapshot to a persistent Key-Value Store so history builds up over time
5. Generates a self-contained HTML report and saves it to the same store
6. Emails the report to you (if `emailTo` is set)

You set it on a cron schedule in the Apify Console (e.g. every hour or once a day) and it runs completely hands-off.

---

### Report preview

The email / HTML report is split into two parts:

**Overview cards** — account-wide numbers at a glance:
- Total Revenue, Cost, Net Profit, Margin (month to date)
- Total Runs Today, Success Rate, New Paying Users, New Free Users

**Actor breakdown** — three collapsible sections:

| Section | When an actor ends up here |
|---|---|
| 🔴 Needs Attention | Zero runs today (but had runs before), success rate below 50%, or a sudden cost spike |
| 🟡 Watch Closely | New paying users today, revenue moved >20%, or run count jumped/dropped >50% |
| 🟢 On Track | Everything else |

Each actor row is expandable and shows: monthly revenue/cost/profit/margin, today's run breakdown, daily run and result averages, cost per 1k results, and paying/free user counts.

---

### Input

| Field | Required | Default | Description |
|---|---|---|---|
| `apifyToken` | ✅ | — | Your Apify API token. Found at **Console → Settings → Integrations**. |
| `emailTo` | — | — | Email address to send the report to. Leave blank to skip email (report still saves to KV store). |
| `snapshotStoreName` | — | `apify-actor-monitor` | Name of the Key-Value Store where snapshots and reports are kept. |

---

### Output

**Dataset** — one record per run, visible in the Apify Console UI:

```json
{
  "date": "2026-04-21",
  "capturedAt": "2026-04-21T12:00:00.000Z",
  "totalRevenue": 1234.67,
  "totalCost": 14.46,
  "netProfit": 1220.21,
  "overallMargin": 0.9883,
  "avgCostPer1000Results": 0.2371,
  "todayRevenue": 2.64,
  "todayCost": 0.01,
  "todayRuns": 604,
  "todaySucceeded": 602,
  "todayFailed": 2,
  "todaySuccessRate": 99.67,
  "todayPayingUsers": 87,
  "todayFreeUsers": 12,
  "actorsMonitored": 40,
  "statusCounts": { "red": 2, "yellow": 5, "green": 33 },
  "topActorsByRevenue": [ ... ],
  "flaggedActors": [ ... ],
  "reportUrl": "https://api.apify.com/v2/key-value-stores/.../records/report-2026-04-21"
}
````

**Key-Value Store** — the named store (`apify-actor-monitor` by default) keeps:

- `snapshot_YYYY-MM-DD` — the full raw snapshot for each day (indefinitely)
- `snapshot_latest` — always the most recent snapshot (used for diffing)
- `report-YYYY-MM-DD` — the HTML report file, openable in any browser

***

### How to set up

#### 1. Get your Apify API token

Go to [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations) and copy your Personal API token.

#### 2. Configure input

In the Apify Console, open your deployed Actor and fill in the input form:

- **Apify API Token** — paste your token
- **Report Email Address** — where you want the report sent
- **Snapshot Store Name** — leave as default unless you want a custom name

#### 3. Run it manually once

Click **Start** to verify everything works. Check the **Dataset** tab to see the output record and the **Key-Value Store** tab to confirm the HTML report was saved.

#### 4. Set a schedule

Go to **Schedules** in the Apify Console and create a new schedule:

- **Cron expression**: `0 20 * * *` — runs daily at 20:00 UTC (or adjust to your preferred time)
- **Actor**: select this Actor
- **Input**: same as above

That's it. You'll get a daily email with the full report, and every dataset row links directly to the stored HTML file.

***

### File structure

```
src/
├── main.js       Entry point — reads input, orchestrates everything
├── fetcher.js    All API calls to Apify analytics endpoints
├── storage.js    Key-Value Store helpers (open / read / write snapshots)
├── diff.js       Compares two snapshots and produces the diff + status tags
└── report.js     Generates the self-contained HTML report string
.actor/
├── actor.json         Actor metadata
└── input_schema.json  Input form definition
Dockerfile             Uses apify/actor-node:20
```

***

### Status logic explained

The diff engine compares the new snapshot against the previous one:

- **Red** if any of:
  - Actor had runs before but has zero today
  - Today's success rate is below 50%
  - Today's compute cost is more than 2× the previous day's cost

- **Yellow** if any of:
  - New paying users appeared today
  - Revenue changed by more than 20% vs the previous snapshot
  - Run count changed by more than 50% vs the daily average

- **Green** — everything else

On the very first run (no previous snapshot yet), all actors are shown as green since there is nothing to compare against.

***

### Tech stack

- **Runtime**: Node.js 20 on the Apify platform
- **Storage**: Apify Named Key-Value Store (persists across runs indefinitely)
- **Scheduling**: Apify built-in Schedules (cron)
- **Email**: Apify Send Mail Actor (`e643gqfZae2TfQEbA`)
- **Language**: JavaScript (ESM)
- **Dependencies**: `apify`, `apify-client`

# Actor input Schema

## `apifyToken` (type: `string`):

Your Apify API token. Used to fetch analytics data and send the email report.

## `emailTo` (type: `string`):

Email address to deliver the HTML report to. Leave empty to skip sending. If you are on the free plan, use your email which is connected to your Apify account otherwise the email sending will reject it.

## `snapshotStoreName` (type: `string`):

Name of the named Key-Value Store used for persistent snapshots across runs.

## Actor input object example

```json
{
  "snapshotStoreName": "apify-actor-monitor"
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("thenetaji/apify-actor-monitor").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("thenetaji/apify-actor-monitor").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 '{}' |
apify call thenetaji/apify-actor-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=thenetaji/apify-actor-monitor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Apify Actor Monitor",
        "description": "Monitors your Apify account actor performance. Takes daily snapshots, computes diffs, and delivers an HTML report via email.",
        "version": "0.1",
        "x-build-id": "CYiRBtKdr6sSrgfte"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/thenetaji~apify-actor-monitor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-thenetaji-apify-actor-monitor",
                "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/thenetaji~apify-actor-monitor/runs": {
            "post": {
                "operationId": "runs-sync-thenetaji-apify-actor-monitor",
                "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/thenetaji~apify-actor-monitor/run-sync": {
            "post": {
                "operationId": "run-sync-thenetaji-apify-actor-monitor",
                "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": [
                    "apifyToken"
                ],
                "properties": {
                    "apifyToken": {
                        "title": "Apify API Token",
                        "type": "string",
                        "description": "Your Apify API token. Used to fetch analytics data and send the email report."
                    },
                    "emailTo": {
                        "title": "Report Email Address",
                        "type": "string",
                        "description": "Email address to deliver the HTML report to. Leave empty to skip sending. If you are on the free plan, use your email which is connected to your Apify account otherwise the email sending will reject it."
                    },
                    "snapshotStoreName": {
                        "title": "Snapshot Store Name",
                        "type": "string",
                        "description": "Name of the named Key-Value Store used for persistent snapshots across runs.",
                        "default": "apify-actor-monitor"
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```