From fe0f73136163d5da303ff59fba41c8cbc68502d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:51:17 +0200 Subject: [PATCH 1/3] docs: add status message section to Actor lifecycle page Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/02_concepts/01_actor_lifecycle.mdx | 13 +++++++++++ docs/02_concepts/code/status_message.ts | 30 +++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 docs/02_concepts/code/status_message.ts diff --git a/docs/02_concepts/01_actor_lifecycle.mdx b/docs/02_concepts/01_actor_lifecycle.mdx index 9d1511607d..6402ec5ff6 100644 --- a/docs/02_concepts/01_actor_lifecycle.mdx +++ b/docs/02_concepts/01_actor_lifecycle.mdx @@ -13,6 +13,7 @@ import CodeBlock from '@theme/CodeBlock'; import MainSource from '!!raw-loader!./apify_platform_main.ts'; import InitExitSource from '!!raw-loader!./apify_platform_init_exit.ts'; +import StatusMessageSource from '!!raw-loader!./code/status_message.ts'; [Apify](https://apify.com) is a platform built to serve large-scale and high-performance web scraping and automation needs. It provides easy access to compute instances (_Actors_), @@ -198,6 +199,18 @@ When the `Dataset` is stored on the - [Datasets API reference](https://docs.apify.com/api/v2#/reference/datasets) - [Request queues API reference](https://docs.apify.com/api/v2#/reference/request-queues) +## Status messages + +Status messages are human-readable messages that provide information about an Actor's progress. Unlike logs, status messages are visible at a glance in the Apify Console on the Actor run details page, making them useful for monitoring long-running Actors without digging through logs. + +Use [`Actor.setStatusMessage()`](https://sdk.apify.com/api/apify/class/Actor#setStatusMessage) to update the status message at meaningful milestones during your Actor's execution. Avoid updating it on every single item — focus on key transitions like starting a new phase, reaching a progress milestone, or completing the run. + +{StatusMessageSource} + +The SDK only sends an API request when the status message actually changes, so you don't need to worry about duplicate updates. + +When your Actor finishes, you can mark the final status message as **terminal** using the `isStatusMessageTerminal` option. A terminal status message persists after the run completes, so users can see the final result at a glance. + ## Environment variables The following are some additional environment variables specific to Apify platform. More Crawlee specific environment variables could be found in the Environment Variables guide. diff --git a/docs/02_concepts/code/status_message.ts b/docs/02_concepts/code/status_message.ts new file mode 100644 index 0000000000..2be618b08e --- /dev/null +++ b/docs/02_concepts/code/status_message.ts @@ -0,0 +1,30 @@ +import { Actor } from 'apify'; + +await Actor.init(); + +// highlight-start +await Actor.setStatusMessage('Fetching the list of URLs...'); +// highlight-end + +// Simulate some work +const urls = [ + 'https://example.com/1', + 'https://example.com/2', + 'https://example.com/3', +]; + +for (let i = 0; i < urls.length; i++) { + // Process each URL... + // highlight-start + await Actor.setStatusMessage(`Processing ${i + 1} of ${urls.length} URLs`); + // highlight-end +} + +// highlight-start +// Mark the final status message as terminal +await Actor.setStatusMessage('All URLs processed successfully!', { + isStatusMessageTerminal: true, +}); +// highlight-end + +await Actor.exit(); From 018835dc3f2b360e58f6a975a440f1e8bd786537 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 14 Apr 2026 13:19:49 +0200 Subject: [PATCH 2/3] docs: improve status message section prose and formatting Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/02_concepts/01_actor_lifecycle.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/02_concepts/01_actor_lifecycle.mdx b/docs/02_concepts/01_actor_lifecycle.mdx index 6402ec5ff6..0d943e5576 100644 --- a/docs/02_concepts/01_actor_lifecycle.mdx +++ b/docs/02_concepts/01_actor_lifecycle.mdx @@ -201,15 +201,15 @@ When the `Dataset` is stored on the ## Status messages -Status messages are human-readable messages that provide information about an Actor's progress. Unlike logs, status messages are visible at a glance in the Apify Console on the Actor run details page, making them useful for monitoring long-running Actors without digging through logs. +[Status messages](/platform/actors/development/programming-interface/status-messages) are lightweight, human-readable progress indicators displayed with the Actor run in the Apify Console (separate from logs). Use them to communicate high-level phases or milestones, such as "Fetching list", "Processed 120/500 pages", or "Uploading results". -Use [`Actor.setStatusMessage()`](https://sdk.apify.com/api/apify/class/Actor#setStatusMessage) to update the status message at meaningful milestones during your Actor's execution. Avoid updating it on every single item — focus on key transitions like starting a new phase, reaching a progress milestone, or completing the run. +Update the status only when the user's understanding of progress changes - avoid frequent updates for every processed item. Detailed information should go to logs or storages (Dataset, Key-value store) instead. -{StatusMessageSource} +Use `Actor.setStatusMessage()` to set the message: -The SDK only sends an API request when the status message actually changes, so you don't need to worry about duplicate updates. +{StatusMessageSource} -When your Actor finishes, you can mark the final status message as **terminal** using the `isStatusMessageTerminal` option. A terminal status message persists after the run completes, so users can see the final result at a glance. +The SDK only sends an API request when the message text changes, so repeating the same message incurs no additional cost. ## Environment variables From d0cdc8eaddf934fafad57dde01daa7b68ce85f7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 14 Apr 2026 13:27:04 +0200 Subject: [PATCH 3/3] fix broken link --- docs/02_concepts/01_actor_lifecycle.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/02_concepts/01_actor_lifecycle.mdx b/docs/02_concepts/01_actor_lifecycle.mdx index 0d943e5576..2e556b539d 100644 --- a/docs/02_concepts/01_actor_lifecycle.mdx +++ b/docs/02_concepts/01_actor_lifecycle.mdx @@ -201,7 +201,7 @@ When the `Dataset` is stored on the ## Status messages -[Status messages](/platform/actors/development/programming-interface/status-messages) are lightweight, human-readable progress indicators displayed with the Actor run in the Apify Console (separate from logs). Use them to communicate high-level phases or milestones, such as "Fetching list", "Processed 120/500 pages", or "Uploading results". +[Status messages](https://docs.apify.com//platform/actors/development/programming-interface/status-messages) are lightweight, human-readable progress indicators displayed with the Actor run in the Apify Console (separate from logs). Use them to communicate high-level phases or milestones, such as "Fetching list", "Processed 120/500 pages", or "Uploading results". Update the status only when the user's understanding of progress changes - avoid frequent updates for every processed item. Detailed information should go to logs or storages (Dataset, Key-value store) instead.