{ "openapi": "3.0.1", "info": { "title": "Actors Monitoring", "version": "1.0", "x-build-id": "Pf9ceUSFpfrGCahNI" }, "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", "properties": { "actorMode": { "title": "Mode", "enum": [ "monthly", "weekly", "compare" ], "type": "string", "description": "**Monthly** builds a usage report (Excel workbook, HTML dashboard, email digest) over the last N calendar months. **Weekly** builds the same report over the last N calendar weeks (Monday–Sunday). **Compare** checks the latest run of each monitored actor/task against a baseline and emails an alert when something changed. Default: `monthly`.", "default": "monthly" }, "emailRecipients": { "title": "Email recipients", "type": "array", "description": "Email addresses that receive the report. Leave empty to skip email (artifacts are still saved to storage). Default: none.", "items": { "type": "string" } }, "actorNameInclude": { "title": "Include actors", "type": "array", "description": "Only monitor actors whose name contains one of these substrings (case-insensitive). Leave empty to monitor **all** actors in the account. Overridden by *Actor name regex* when that is set. Default: all actors.", "items": { "type": "string" } }, "useDirectActorRuns": { "title": "Use direct actor runs", "type": "boolean", "description": "When enabled, runs are collected directly per actor instead of via saved tasks; all task filters below are ignored. Default: `false` (task discovery).", "default": false }, "actorNameExclude": { "title": "Exclude actors", "type": "array", "description": "Skip actors whose name contains one of these substrings. Applied after includes; overridden by *Actor name regex*. Default: none.", "items": { "type": "string" } }, "actorNamePattern": { "title": "Actor name regex", "type": "string", "description": "Regular expression matched against actor names. When set, it replaces the include/exclude substring lists above. Default: unset." }, "taskNameInclude": { "title": "Include tasks", "type": "array", "description": "Only monitor saved tasks whose name contains one of these substrings. Ignored when *Use direct actor runs* is enabled. Default: all tasks of the selected actors.", "items": { "type": "string" } }, "taskNameExclude": { "title": "Exclude tasks", "type": "array", "description": "Skip tasks whose name contains one of these substrings. Ignored when *Use direct actor runs* is enabled. Default: none.", "items": { "type": "string" } }, "taskNamePattern": { "title": "Task name regex", "type": "string", "description": "Regular expression matched against task names; replaces the task include/exclude lists when set. Ignored when *Use direct actor runs* is enabled. Default: unset." }, "actorIds": { "title": "Actor IDs", "type": "array", "description": "Monitor exactly these actor IDs, skipping name-based discovery entirely. Default: unset (use name filters).", "items": { "type": "string" } }, "filterRunsByStatus": { "title": "Run statuses", "type": "array", "description": "Only collect runs with these statuses. Default when omitted: all statuses in monthly/weekly mode; `SUCCEEDED` only in compare mode.", "items": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "ABORTED", "RUNNING", "TIMED-OUT" ], "enumTitles": [ "Succeeded", "Failed", "Aborted", "Running", "Timed out" ] } }, "runInputFilters": { "title": "Run input filters", "type": "array", "description": "Include or exclude runs by their **input** values. Each rule: `{\"field\": \"country\", \"operator\": \"equals\", \"value\": \"US\", \"action\": \"include\"}`. Operators: equals, notEquals, exists, notExists, in, notIn, contains. Maximum 20 rules. Explicitly compared run IDs are never filtered out. Default: no filtering.", "items": { "type": "object" } }, "runInputFilterMode": { "title": "Include-rule combination", "enum": [ "all", "any" ], "type": "string", "description": "How multiple *include* rules combine. Exclude rules always drop a run on match. Default: `all`.", "default": "all" }, "outputMode": { "title": "Output mode", "enum": [ "email", "dataset", "both" ], "type": "string", "description": "Where results go. `dataset` skips email even when recipients are set. Storage artifacts (Excel, dashboard, manifest) are always saved. Default: `email`.", "default": "email" }, "emailSubject": { "title": "Email subject template", "type": "string", "description": "Custom subject. Placeholders: `{mode}`, `{date}`, `{actorCount}`, `{status}`. Default: a mode-appropriate subject." }, "emailSections": { "title": "Email sections", "type": "object", "description": "Toggle report sections on/off. Keys (all default `true`): `showCostBreakdown`, `showRunLinks`; compare-mode only: `showSchemaChanges`, `showTrendAnalysis`, `showAnomalyDetection`, `showBuildChanges`, `showFieldDiscovery`. Default: all sections shown." }, "emailFooterText": { "title": "Email footer text", "type": "string", "description": "Custom line appended to the email footer. Default: none." }, "dryRun": { "title": "Dry run", "type": "boolean", "description": "Build everything but send no email — the rendered email HTML is saved to the key-value store as `dry-run-email-preview.html` instead. Default: `false`.", "default": false }, "monthsToAnalyze": { "title": "Months to analyze", "minimum": 1, "maximum": 24, "type": "integer", "description": "How many calendar months of runs to report on. Ignored when a custom date range is set below. Default: `3`.", "default": 3 }, "includeCurrentMonth": { "title": "Include current month", "type": "boolean", "description": "Whether the (partial) current month counts as one of the analyzed months. Applies to `actorMode: monthly` only. Default: `true`.", "default": true }, "weeksToAnalyze": { "title": "Weeks to analyze", "minimum": 1, "maximum": 52, "type": "integer", "description": "How many calendar weeks (Monday–Sunday) of runs to report on. Ignored when a custom date range is set below. Default: `4`.", "default": 4 }, "includeCurrentWeek": { "title": "Include current week", "type": "boolean", "description": "Whether the (partial) current week counts as one of the analyzed weeks. Applies to `actorMode: weekly` only. Default: `true`.", "default": true }, "dateRangeStart": { "title": "Date range start", "type": "string", "description": "Custom period start (`YYYY-MM-DD`). When both start and end are set, they replace *Months to analyze*. Required if an end date is set. Default: unset." }, "dateRangeEnd": { "title": "Date range end", "type": "string", "description": "Custom period end (`YYYY-MM-DD`), inclusive. Must be on or after the start date. Default: today." }, "topNActors": { "title": "Top-N size", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many actors appear in each dashboard ranking (top cost, top failing, health). Default: `5`.", "default": 5 }, "customDimensions": { "title": "Custom report dimensions", "type": "array", "description": "Group the report by run fields instead of by reporting period. Up to 5 dimensions; each: `{\"field\": \"input.country\", \"label\": \"Country\", \"fallback\": \"Unknown\"}` with optional `buckets`, `sort` (asc/desc/count) and `transform` (dayOfWeek/hourOfDay/weekNumber/successFailure). Default: group by calendar month (monthly mode) or ISO week (weekly mode). See the field-comparison guide for recipes.", "items": { "type": "object" } }, "enableAggregation": { "title": "Enable product aggregation", "type": "boolean", "description": "Adds the *Aggregated Insights* view: item volume per product dimension with period-over-period growth and yield alerts. Default: `true`.", "default": true }, "saveHtmlDashboard": { "title": "Save HTML dashboard", "type": "boolean", "description": "Saves a self-contained interactive HTML dashboard (KPIs, trend charts, rankings) to the key-value store and links it from the email. Default: `true`.", "default": true }, "healthScoreWeights": { "title": "Health score weights", "type": "object", "description": "Weights of the 0–100 actor health score. Keys (must sum to 1.0): `successRate` (default 0.47), `zeroItemInverse` (0.29), `costEfficiency` (0.24). Omit any key to use its default. Default: unset (use defaults)." }, "compareMode": { "title": "Comparison mode", "enum": [ "last2", "lastVsBaseline", "lastVsAverage" ], "type": "string", "description": "How the baseline is chosen for each monitored actor/task. `lastVsBaseline` requires *Baseline run ID*; `lastVsAverage` averages the last *Baseline run count* runs. Ignored entirely when both explicit run IDs below are set. Default: `last2`.", "default": "last2" }, "baselineRunId": { "title": "Baseline run ID", "type": "string", "description": "Pinned known-good run compared against the latest run. Required when *Comparison mode* is `lastVsBaseline`; ignored when explicit run IDs are set. Default: unset." }, "baselineRunCount": { "title": "Baseline run count", "minimum": 2, "maximum": 20, "type": "integer", "description": "How many historical runs are averaged when *Comparison mode* is `lastVsAverage`. Default: `5`.", "default": 5 }, "compareRunId1": { "title": "Explicit run ID — baseline", "type": "string", "description": "Compare exactly two runs: this run as baseline versus *Explicit run ID — current*. Both IDs must be set together and must differ. When set, this **takes full precedence** over *Comparison mode* and *Baseline run ID*. Default: unset." }, "compareRunId2": { "title": "Explicit run ID — current", "type": "string", "description": "The run treated as \"current\" in an explicit two-run comparison. Must be set together with the baseline run ID above. Default: unset." }, "maxDatasetItems": { "title": "Max dataset items per run", "minimum": 100, "maximum": 10000, "type": "integer", "description": "How many dataset items to fetch per run for field-level comparison. Default: `1000`.", "default": 1000 }, "enableCompareExcel": { "title": "Save comparison workbook", "type": "boolean", "description": "Saves an Excel comparison report (`compare-report.xlsx`) to the key-value store. Default: `false`.", "default": false }, "combineEmails": { "title": "Combine into one email", "type": "boolean", "description": "Send one consolidated email covering all compared actors/tasks instead of one email each. Monthly and weekly modes always send a single email. Default: `true`.", "default": true }, "fieldsAndCompareStrategy": { "title": "Fields & strategies", "type": "object", "description": "Which dataset fields to compare and how, e.g. `{\"results.price\": \"average\", \"items\": {\"strategy\": \"count\", \"lowerIsBetter\": false}}`. Use `[]` to reach into arrays of objects (`reviews[].rating`). 25 strategies available (count, sum, average, coverage, null_rate, ratio, …) — see the field-comparison guide; `min`/`max` also understand ISO-date strings (e.g. newest `reviews[].reviewDate`). **Omitting this field — or passing an empty object `{}` — runs field *discovery* instead: the report suggests a configuration but compares nothing.** Default: discovery mode." }, "excludeFields": { "title": "Exclude fields", "type": "array", "description": "Field paths to skip. With strategies configured above: excluded from comparison. Without: omitted from the discovery report. Default: none.", "items": { "type": "string" } }, "enableTrendAnalysis": { "title": "Enable trend analysis", "type": "boolean", "description": "Analyzes items/runtime/cost across recent runs (linear regression + streaks) and adds a Trends section to the report. Default: `false`.", "default": false }, "trendRunCount": { "title": "Trend run count", "minimum": 3, "maximum": 50, "type": "integer", "description": "How many recent runs feed the trend analysis. Default: `10`.", "default": 10 }, "enableAnomalyDetection": { "title": "Enable anomaly detection", "type": "boolean", "description": "Flags runs whose metrics deviate from recent history by more than the multiplier below (z-score). Works independently of trend analysis. Default: `false`.", "default": false }, "anomalyStdDevMultiplier": { "title": "Anomaly sensitivity (σ)", "minimum": 1, "maximum": 5, "type": "number", "description": "Standard-deviation multiplier for flagging anomalies — lower is more sensitive. Default: `2`.", "default": 2 }, "alerts": { "title": "Alert thresholds", "type": "object", "description": "One place for every \"how big a change matters\" setting. Keys (all optional): `changePercent` (default 5 — compare-mode email gate), `itemsCount`/`runtimeSecs`/`costUsd` (each `{warning, critical}` **percent-change** severity bands for compare mode), `avgRuntimeSecs`/`avgCostUsd` (absolute monthly/weekly Threshold Breaches in seconds / USD), `custom` (bands per compared field path; also `failureRate`/`zeroItemRate` for monthly), `yieldDropPercent` (default 20 — aggregation yield alert). Default: sensible compare thresholds." }, "notifyOnSignificantChange": { "title": "Only email on significant change", "type": "boolean", "description": "Compare mode: send the alert email only when at least one metric changed by `alerts.changePercent` or more. Default: `true`.", "default": true }, "alwaysSendSummary": { "title": "Send all-clear summary", "type": "boolean", "description": "Compare mode: when nothing significant changed, still send a short \"all clear\" summary email. Default: `false`.", "default": false }, "pricePerItem": { "title": "Price per item (USD)", "minimum": 0, "type": "number", "description": "Your client-facing price per dataset item. When set, reports add Billed and Margin columns (billed = items × price, margin = billed − Apify cost). Default: unset (billing columns hidden)." }, "maxRuns": { "title": "Max runs per actor/task", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Cap on runs fetched per monitored actor or task. Default: `100`.", "default": 100 }, "concurrencyLimit": { "title": "Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many actors/tasks are collected in parallel. Default: `5`.", "default": 5 }, "circuitBreakerThreshold": { "title": "Circuit breaker threshold", "minimum": 1, "maximum": 50, "type": "integer", "description": "Abort the run once at least this many actors/tasks fail to collect *and* at least half of the processed items have failed. If the first few processed items all fail (e.g. an invalid token), the run aborts immediately without waiting for the rest. Default: `3`.", "default": 3 }, "token": { "title": "Apify API token", "type": "string", "description": "Token of the account to monitor. Default: the account running this actor." }, "debug": { "title": "Debug logging", "type": "boolean", "description": "Verbose logs for troubleshooting. Default: `false`.", "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 } } } } } } } } } }