{ "openapi": "3.0.1", "info": { "title": "Actors Monitoring", "version": "1.0", "x-build-id": "wXFK08O3kibMz8UGD" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hamza.alwan~actors-monitoring/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hamza.alwan-actors-monitoring", "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/hamza.alwan~actors-monitoring/runs": { "post": { "operationId": "runs-sync-hamza.alwan-actors-monitoring", "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/hamza.alwan~actors-monitoring/run-sync": { "post": { "operationId": "run-sync-hamza.alwan-actors-monitoring", "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": [ "actorMode" ], "properties": { "actorMode": { "title": "Report Mode", "enum": [ "compare", "monthly" ], "type": "string", "description": "Choose which type of report to generate. 'Compare Runs' compares recent runs of actors against each other to detect changes. 'Monthly Report' generates long-term historical metrics and volume aggregations.", "default": "monthly" }, "useDirectActorRuns": { "title": "Use Direct Actor Runs (Skip Tasks)", "type": "boolean", "description": "If enabled, fetches runs directly from Actors instead of going through Tasks. Enable this if you run your Actors directly without wrapping them in Apify Tasks. (Task filters are ignored if this is enabled).", "default": false }, "actorNameInclude": { "title": "Include Actors", "type": "array", "description": "Filter actors by name substring (case-sensitive). Only actors containing any of these substrings will be processed. Leave array empty to include all.", "items": { "type": "string" } }, "actorNameExclude": { "title": "Exclude Actors", "type": "array", "description": "Skip actors whose names contain any of these substrings (case-sensitive).", "items": { "type": "string" } }, "actorNamePattern": { "title": "Actor Name Regex Pattern", "type": "string", "description": "Regex pattern for actor name filtering. Takes precedence over substring-based include/exclude filters when provided." }, "taskNameInclude": { "title": "Include Tasks (Ignored in useDirectActorRuns: true)", "type": "array", "description": "Only process tasks whose names contain any of these substrings (case-sensitive). Leave array empty to include all. (Ignored when Direct Actor Runs is enabled)", "items": { "type": "string" } }, "taskNameExclude": { "title": "Exclude Tasks (Ignored in useDirectActorRuns: true)", "type": "array", "description": "Skip tasks whose names contain any of these substrings (case-sensitive). (Ignored when Direct Actor Runs is enabled)", "items": { "type": "string" } }, "taskNamePattern": { "title": "Task Name Regex Pattern", "type": "string", "description": "Regex pattern for task name filtering. Takes precedence over substring-based include/exclude filters when provided. Ignored when Direct Actor Runs is enabled." }, "actorIds": { "title": "Specific Actor IDs", "type": "array", "description": "Specific Apify actor IDs to monitor. When provided, skips the actor/task discovery process and monitors only these explicit IDs directly. Each ID must be 8-64 alphanumeric characters (A-Z, a-z, 0-9).", "items": { "type": "string" } }, "outputMode": { "title": "Output Mode", "enum": [ "email", "dataset", "both" ], "type": "string", "description": "Where to output results. 'email' sends reports via email, 'dataset' pushes to the default dataset (skips email), 'both' does both.", "default": "email" }, "emailRecipients": { "title": "Email Recipients", "type": "array", "description": "List of email addresses to receive the generated reports.", "items": { "type": "string" } }, "combineEmails": { "title": "Combine Emails", "type": "boolean", "description": "When enabled, all comparisons are combined into a single email with one unified table. When disabled, each comparison is sent as a separate email.", "default": true }, "emailSubject": { "title": "Custom Email Subject", "type": "string", "description": "Custom email subject template. Supports placeholders: {mode}, {date}, {actorCount}, {status}. If not provided, a default subject is generated." }, "emailSections": { "title": "Email Sections Visibility", "type": "object", "description": "Control which sections appear in email reports. Each key toggles a report section on/off.", "default": { "showCostBreakdown": true, "showSchemaChanges": true, "showTrendAnalysis": true, "showAnomalyDetection": true, "showBuildChanges": true, "showRunLinks": true, "showFieldDiscovery": true } }, "emailFooterText": { "title": "Custom Email Footer", "type": "string", "description": "Custom footer text appended to the bottom of email reports." }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Optional generic webhook URL. The actor POSTs JSON payloads on compare alerts and monthly report completion." }, "dryRun": { "title": "Dry Run Mode", "type": "boolean", "description": "When enabled, the actor performs all processing (data fetching, comparison, report generation) but skips sending emails. The generated HTML report is saved to Key-Value Store for review. Useful for testing configurations without sending notifications.", "default": false }, "maxRuns": { "title": "Max Runs per Actor/Task", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Maximum number of runs to fetch and process per actor or task. Higher values provide more comprehensive data but linearly increase processing time and API requests.", "default": 100 }, "concurrencyLimit": { "title": "Concurrency Limit", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of actors/tasks processed in parallel during run collection.", "default": 5 }, "circuitBreakerThreshold": { "title": "Circuit Breaker Threshold", "minimum": 1, "maximum": 50, "type": "integer", "description": "Number of collection failures before aborting the run to avoid partial reports.", "default": 3 }, "monthsToAnalyze": { "title": "Months to Analyze", "minimum": 1, "maximum": 24, "type": "integer", "description": "Number of calendar months to analyze for monthly reports. By default, the current in-progress month is included, so 3 means current month plus the previous 2 months. This setting is ignored if Date Range Start and Date Range End are explicitly mapped out.", "default": 3 }, "includeCurrentMonth": { "title": "Include Current Month", "type": "boolean", "description": "When enabled, monthly reports include the current in-progress calendar month. Disable this to analyze only completed calendar months.", "default": true }, "dateRangeStart": { "title": "Date Range Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "ISO date string (e.g., '2025-01-01') for a custom date range start. Overrides 'Months to Analyze' when provided." }, "dateRangeEnd": { "title": "Date Range End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "ISO date string (e.g., '2025-12-31') for a custom date range end. Defaults to the current date if not provided." }, "topNActors": { "title": "Top N Actors in Monthly Reports", "minimum": 1, "maximum": 20, "type": "integer", "description": "Number of top actors to highlight in monthly report rankings (e.g., top actors by highest cost, most runs, most failures).", "default": 5 }, "monthlyFilterStatus": { "title": "Monthly Report: Filter Runs by Status", "type": "array", "description": "Select which run statuses to include in monthly reports. Typically all statuses. Leave empty to include all.", "items": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "ABORTED", "RUNNING", "TIMED-OUT" ], "enumTitles": [ "Succeeded", "Failed", "Aborted", "Running", "Timed Out" ] }, "default": [ "SUCCEEDED", "FAILED", "ABORTED", "RUNNING", "TIMED-OUT" ] }, "customDimensions": { "title": "Custom Dimensions for Monthly Reports", "type": "array", "description": "Define custom dimensions to organize runs in monthly reports beyond default time-based grouping. Only used in monthly mode. Each item supports: field (dot-notation path, e.g. actorName or stats.runTimeSecs), label, fallback, buckets (numeric ranges), sort (asc, desc, or count), and transform (dayOfWeek, hourOfDay, weekNumber, successFailure). See README section 'Custom Dimensions (Monthly)' for examples.", "items": { "type": "object", "properties": { "field": { "type": "string", "title": "Field Path", "description": "Path to extract values from run data using dot notation" }, "label": { "type": "string", "title": "Display Label", "description": "Human-readable label for this dimension" }, "fallback": { "type": "string", "title": "Fallback Value", "description": "Default value when field is missing or null" }, "buckets": { "type": "array", "title": "Numeric Buckets", "description": "Define numeric ranges for grouping continuous values. Each bucket has a 'max' (upper bound, omit for catch-all) and 'label'. Order by ascending max.", "items": { "type": "object", "properties": { "max": { "type": "number", "title": "Upper Bound", "description": "Upper bound for this bucket. Omit for a catch-all bucket that captures all remaining values." }, "label": { "type": "string", "title": "Bucket Label", "description": "Display label for this bucket range in reports." } }, "required": [ "label" ] } }, "sort": { "type": "string", "title": "Sort Order", "description": "Sort dimension values: 'asc' (alphabetical), 'desc' (reverse), 'count' (most runs first).", "enum": [ "asc", "desc", "count" ] }, "transform": { "type": "string", "title": "Preset Transform", "description": "Apply a preset transform to extracted values before grouping: dayOfWeek, hourOfDay, weekNumber, successFailure.", "enum": [ "dayOfWeek", "hourOfDay", "weekNumber", "successFailure" ] } }, "required": [ "field" ] } }, "enableAggregation": { "title": "Enable Monthly Aggregation", "type": "boolean", "description": "When enabled, computes monthly aggregation metrics (e.g., current vs previous month product counts, success rates) and exports a clean JSON dashboard metrics file to the Key-Value store. This enables tracking volume growth over time.", "default": true }, "aggregationYieldAlertThreshold": { "title": "Yield Alert Threshold (%)", "minimum": 1, "maximum": 99, "type": "number", "description": "Percentage drop threshold for triggering a Yield Alert on the aggregate level. If an actor's aggregated monthly product count drops by more than this percentage compared to the previous month, it will be flagged in the email alerts as a severe anomaly.", "default": 20 }, "saveHtmlDashboard": { "title": "Save HTML Dashboard", "type": "boolean", "description": "When enabled, saves the monthly email HTML to the Key-Value store as an HTML dashboard artifact.", "default": false }, "healthScoreWeights": { "title": "Health Score Weights", "required": [ "successRate", "zeroItemInverse", "costEfficiency", "trend" ], "type": "object", "description": "Optional override for monthly health score component weights. All four values are required and must sum to 1.0. Defaults: successRate 0.47, zeroItemInverse 0.29, costEfficiency 0.24, trend 0 (deprecated axis, keep at 0).", "properties": { "successRate": { "title": "Success Rate Weight", "description": "Weight for the success-rate component (default 0.47).", "type": "number", "minimum": 0, "maximum": 1 }, "zeroItemInverse": { "title": "Zero-Item Inverse Weight", "description": "Weight for the zero-item inverse component (default 0.29).", "type": "number", "minimum": 0, "maximum": 1 }, "costEfficiency": { "title": "Cost Efficiency Weight", "description": "Weight for the cost-efficiency component (default 0.24).", "type": "number", "minimum": 0, "maximum": 1 }, "trend": { "title": "Trend Weight (deprecated, use 0)", "description": "Deprecated axis; keep at 0. All four weights must sum to 1.0.", "type": "number", "minimum": 0, "maximum": 1 } } }, "compareFilterStatus": { "title": "Compare Mode: Filter Runs by Status", "type": "array", "description": "Select which run statuses to include in comparison reports. Defaults to Succeeded only. Failed runs generally shouldn't be compared for dataset changes.", "items": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "ABORTED", "RUNNING", "TIMED-OUT" ], "enumTitles": [ "Succeeded", "Failed", "Aborted", "Running", "Timed Out" ] }, "default": [ "SUCCEEDED" ] }, "compareMode": { "title": "Compare Strategy", "enum": [ "last2", "lastVsBaseline", "lastVsAverage" ], "type": "string", "description": "Strategy for selecting which runs to compare. 'Last 2 Runs' compares the two most recent succeeded runs. 'Last vs Baseline Run' compares the latest run against a specific baseline run ID. 'Last vs Average' compares against the rolling average dataset. Ignored when both compareRunId1 and compareRunId2 are provided — those explicit run IDs take precedence.", "default": "last2" }, "compareRunId1": { "title": "First Run ID (Comparison Mode)", "type": "string", "description": "Optional: first run ID for a direct two-run comparison in compare mode. When both compareRunId1 and compareRunId2 are set, they take precedence over compareMode and baselineRunId — the actor compares only these two runs." }, "compareRunId2": { "title": "Second Run ID (Comparison Mode)", "type": "string", "description": "Optional: second run ID for a direct two-run comparison in compare mode. Must be provided together with compareRunId1; when both are set, they override compareMode and baselineRunId." }, "baselineRunId": { "title": "Baseline Run ID", "type": "string", "description": "Specific run ID to use as baseline. Required when Compare Strategy is set to 'Last vs Baseline Run'." }, "baselineRunCount": { "title": "Baseline Run Count", "minimum": 2, "maximum": 20, "type": "integer", "description": "Number of recent runs to average for baseline comparison when using 'Last vs Average' compare strategy.", "default": 5 }, "maxDatasetItems": { "title": "Max Dataset Items per Run", "minimum": 100, "maximum": 10000, "type": "integer", "description": "Maximum number of dataset items to fetch per run for field-level comparison. Higher values give more accurate field comparisons but exponentially increase processing time and memory usage.", "default": 1000 }, "enableCompareExcel": { "title": "Enable Compare Excel Export", "type": "boolean", "description": "When enabled, generates an Excel comparison report and saves it to the Key-Value store during compare runs.", "default": false }, "fieldsAndCompareStrategy": { "title": "Field Comparison Strategies", "type": "object", "description": "Per-field comparison strategies for compare mode. Each key is a dot-notation field path; the value is a strategy string (shorthand) or an object with strategy, label, lowerIsBetter, threshold, and denominatorField (required for ratio). See README section 'Intelligent Field Comparison' for available strategies and examples." }, "excludeFields": { "title": "Exclude Fields from Comparison", "type": "array", "description": "Field paths to exclude from dataset comparison. When fieldsAndCompareStrategy is configured, matching fields are skipped during comparison. When no strategy is configured, excluded paths are omitted from the auto-discovery report. Useful for filtering noisy fields like timestamps or internal IDs. Uses the same dot notation as fieldsAndCompareStrategy.", "items": { "type": "string" } }, "enableTrendAnalysis": { "title": "Enable Trend Analysis", "type": "boolean", "description": "When enabled, the comparison report includes multi-run trend analysis showing whether metrics are improving, degrading, or stable over time. Uses linear regression on recent runs to detect patterns.", "default": false }, "trendRunCount": { "title": "Trend Run Count", "minimum": 3, "maximum": 50, "type": "integer", "description": "Number of recent runs to include in trend analysis. More runs provide better trend detection but require more data. Only used when Trend Analysis is enabled.", "default": 10 }, "enableAnomalyDetection": { "title": "Enable Anomaly Detection", "type": "boolean", "description": "When enabled, uses standard deviation-based statistical analysis to detect anomalous runs. Requires Trend Analysis to also be enabled (needs historical runs). Flags runs where metrics deviate significantly from the rolling mean.", "default": false }, "anomalyStdDevMultiplier": { "title": "Anomaly Sensitivity (Std Dev Multiplier)", "minimum": 1, "maximum": 5, "type": "number", "description": "Number of standard deviations from the mean to trigger an anomaly alert. Lower values are more sensitive (more alerts), higher values are more conservative. Default: 2 (catches values outside ~95% of normal range). Use 3 for critical-only alerts (~99.7% range).", "default": 2 }, "alertThresholds": { "title": "Alert Thresholds", "type": "object", "description": "

Custom Alert Thresholds

Configure warning and critical percentage thresholds for comparison metrics. When a metric change exceeds a threshold relative to its comparative baseline, the row is flagged with a warning or critical state in the email report.

Default thresholds (if omitted):

" }, "significanceThreshold": { "title": "Significance Threshold (%)", "minimum": 1, "maximum": 50, "type": "number", "description": "Percentage change threshold used with notifyOnSignificantChange. Changes below this value are treated as normal. alertThresholds independently set per-metric warning/critical limits in emails and Excel.", "default": 5 }, "notifyOnSignificantChange": { "title": "Email Only for Significant Changes - Compare Mode", "type": "boolean", "description": "When enabled, comparison emails send only if at least one metric exceeds significanceThreshold (default 5%). alertThresholds below control warning/critical styling independently of this gate.", "default": true }, "alwaysSendSummary": { "title": "Always Send Health Check Summary", "type": "boolean", "description": "When enabled alongside 'Email Only for Significant Changes', sends a short health-check summary email even when no significant changes are detected. Confirms that monitoring ran and everything is within normal thresholds.", "default": false }, "pricePerItem": { "title": "Price Per Item (USD)", "minimum": 0, "type": "number", "description": "Optional client billing rate in USD per scraped item. When set, reports add Total Billed and Margin (billed minus Apify cost) alongside existing Apify cost metrics. Leave empty to disable billing columns." }, "token": { "title": "Apify API Token", "type": "string", "description": "Optional Apify API token. If not provided, the monitor will automatically use the account it is currently running on to look for data (actors, tasks, runs, datasets, etc). If a token IS provided, it will instead use the account associated with that specific token to fetch the data." }, "debug": { "title": "Debug Logging", "type": "boolean", "description": "Enable verbose debug logging for troubleshooting. Produces significantly more log output.", "default": false } } }, "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 } } } } } } } } } }