From c118c8791311668f4341a19bd71ab07c2683e522 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:34:35 +0200 Subject: [PATCH 01/10] docs: distinguish standby URL from web server URL in env vars reference --- .../programming_interface/environment_variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/environment_variables.md b/sources/platform/actors/development/programming_interface/environment_variables.md index 00713b39a8..bb6d21aa0e 100644 --- a/sources/platform/actors/development/programming_interface/environment_variables.md +++ b/sources/platform/actors/development/programming_interface/environment_variables.md @@ -52,9 +52,9 @@ Variables prefixed with `ACTOR_` are defined by the [Actor specification](https: | `ACTOR_BUILD_NUMBER` | Build number of the Actor build used in the run. | | `ACTOR_BUILD_TAGS` | A comma-separated list of tags of the Actor build used in the run. Note that this environment variable is assigned at the time of start of the Actor and doesn't change over time, even if the assigned build tags change. | | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. | -| `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. | +| `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. Each run gets its own URL, which stops working when the run finishes. | | `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. The server also receives messages from the [Actor Standby](/actors/development/programming-interface/standby) mode. | -| `ACTOR_STANDBY_URL` | URL for accessing web servers of Actor runs in the [Actor Standby](/actors/development/programming-interface/standby) mode. | +| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, this URL is the same for all runs of the Actor and is intended to be shared publicly. | | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/actors/development/programming-interface/system-events) from Actor platform. | | `ACTOR_MCP_CONNECTOR_BASE_URL` | Base URL of the Apify MCP Proxy. Connect to an [MCP connector](/integrations/mcp-connectors) at `${ACTOR_MCP_CONNECTOR_BASE_URL}/` using `APIFY_TOKEN` as the bearer token. | From 11f5982bd13ae1bbfc80d3f5e130a0a1f5ca6bd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:34:49 +0200 Subject: [PATCH 02/10] docs: document standby URL semantics and link running-side standby page --- .../programming_interface/actor_standby.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index efa099fc16..a528a3a7a2 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -174,10 +174,22 @@ async def main() -> None: When you send a request to an Actor in Standby mode, the total timeout for receiving the first response is _5 minutes_. Before the platform forwards the request to a specific Actor run, it performs a _run selection_ process to determine the specific Actor run that will handle it. This process has internal timeout of _2 minutes_. +The platform automatically starts and stops Standby runs based on the incoming request load. Runs that receive no requests within the configured idle timeout are terminated, so make sure your Actor [persists its state](./system_events.md) if it needs to survive restarts. To learn how the scaling works and how to configure it, see the [scaling](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration) sections. + ## Getting the URL of the Standby Actor The URL is exposed as an environment variable `ACTOR_STANDBY_URL`. You can also use `Actor.config`, where the `standbyUrl` option is available. +The Standby URL is based on the Actor owner's username and the Actor name, for example: + +```text +https://jane-doe--my-actor.apify.actor +``` + +Unlike the URL of the [container web server](./container_web_server.md), which is unique to each run and stops working when the run finishes, the Standby URL is the same for all runs of the Actor. You can share it publicly, for example in your Actor's README or in an external application that calls the Actor. Always read the URL from the environment variable or the SDK configuration instead of constructing it yourself, as the exact format can vary. + +Requests to the Standby URL are authenticated with the caller's Apify API token. To learn how users authenticate their requests, see the [Actor Standby](../../running/actor_standby.md#how-do-i-authenticate-my-requests) page. + ## Monetization of Actors in Standby mode You can monetize Standby Actors just like any other Actor. From d59fd810d5e096b7c27155902b254fb012e450d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:57:57 +0200 Subject: [PATCH 03/10] docs: tighten standby URL prose and move run lifecycle out of timeouts --- .../development/programming_interface/actor_standby.md | 10 ++++++---- .../programming_interface/environment_variables.md | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index a528a3a7a2..6763c44df9 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -170,23 +170,25 @@ async def main() -> None: +## Run lifecycle in Standby mode + +The platform starts and stops Standby runs automatically based on the incoming request load. A run that receives no requests within the idle timeout is terminated, and a new run starts when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [storage](../../../storage/index.md). To learn how scaling works and how to configure it, see the [scaling](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration) sections. + ## Timeouts When you send a request to an Actor in Standby mode, the total timeout for receiving the first response is _5 minutes_. Before the platform forwards the request to a specific Actor run, it performs a _run selection_ process to determine the specific Actor run that will handle it. This process has internal timeout of _2 minutes_. -The platform automatically starts and stops Standby runs based on the incoming request load. Runs that receive no requests within the configured idle timeout are terminated, so make sure your Actor [persists its state](./system_events.md) if it needs to survive restarts. To learn how the scaling works and how to configure it, see the [scaling](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration) sections. - ## Getting the URL of the Standby Actor The URL is exposed as an environment variable `ACTOR_STANDBY_URL`. You can also use `Actor.config`, where the `standbyUrl` option is available. -The Standby URL is based on the Actor owner's username and the Actor name, for example: +The URL is based on the Actor owner's username and the Actor name, for example: ```text https://jane-doe--my-actor.apify.actor ``` -Unlike the URL of the [container web server](./container_web_server.md), which is unique to each run and stops working when the run finishes, the Standby URL is the same for all runs of the Actor. You can share it publicly, for example in your Actor's README or in an external application that calls the Actor. Always read the URL from the environment variable or the SDK configuration instead of constructing it yourself, as the exact format can vary. +Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor. Note that the exact hostname format differs for some Actors, so always read the URL from the environment variable or the SDK configuration instead of building it from the username and Actor name. Requests to the Standby URL are authenticated with the caller's Apify API token. To learn how users authenticate their requests, see the [Actor Standby](../../running/actor_standby.md#how-do-i-authenticate-my-requests) page. diff --git a/sources/platform/actors/development/programming_interface/environment_variables.md b/sources/platform/actors/development/programming_interface/environment_variables.md index bb6d21aa0e..572bf59d2e 100644 --- a/sources/platform/actors/development/programming_interface/environment_variables.md +++ b/sources/platform/actors/development/programming_interface/environment_variables.md @@ -54,7 +54,7 @@ Variables prefixed with `ACTOR_` are defined by the [Actor specification](https: | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. | | `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. Each run gets its own URL, which stops working when the run finishes. | | `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. The server also receives messages from the [Actor Standby](/actors/development/programming-interface/standby) mode. | -| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, this URL is the same for all runs of the Actor and is intended to be shared publicly. | +| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, it stays the same for all runs of the Actor, so you can share it publicly. | | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/actors/development/programming-interface/system-events) from Actor platform. | | `ACTOR_MCP_CONNECTOR_BASE_URL` | Base URL of the Apify MCP Proxy. Connect to an [MCP connector](/integrations/mcp-connectors) at `${ACTOR_MCP_CONNECTOR_BASE_URL}/` using `APIFY_TOKEN` as the bearer token. | From 5e9a4c1dc0f85717f47c099f9e72cbfa0eae1a70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 17:05:35 +0200 Subject: [PATCH 04/10] docs: address independent review findings on standby additions --- .../development/programming_interface/actor_standby.md | 8 ++++---- .../programming_interface/environment_variables.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index 6763c44df9..f89ca5fa92 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -172,7 +172,7 @@ async def main() -> None: ## Run lifecycle in Standby mode -The platform starts and stops Standby runs automatically based on the incoming request load. A run that receives no requests within the idle timeout is terminated, and a new run starts when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [storage](../../../storage/index.md). To learn how scaling works and how to configure it, see the [scaling](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration) sections. +The platform starts and stops Standby runs automatically based on the incoming request load. It stops a run that receives no requests within the configured idle timeout and starts a new run when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [dataset or key-value store](../../../storage/index.md). To learn how scaling works and how to configure the idle timeout, see the [scaling](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration) sections. ## Timeouts @@ -182,15 +182,15 @@ When you send a request to an Actor in Standby mode, the total timeout for recei The URL is exposed as an environment variable `ACTOR_STANDBY_URL`. You can also use `Actor.config`, where the `standbyUrl` option is available. -The URL is based on the Actor owner's username and the Actor name, for example: +The URL typically combines the Actor owner's username and the Actor name, for example: ```text https://jane-doe--my-actor.apify.actor ``` -Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor. Note that the exact hostname format differs for some Actors, so always read the URL from the environment variable or the SDK configuration instead of building it from the username and Actor name. +Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor. Some Actors use a different hostname format, so always read the URL from the environment variable or the SDK configuration rather than building it yourself. -Requests to the Standby URL are authenticated with the caller's Apify API token. To learn how users authenticate their requests, see the [Actor Standby](../../running/actor_standby.md#how-do-i-authenticate-my-requests) page. +Requests to the Standby URL require an Apify API token. See [how to authenticate your requests](../../running/actor_standby.md#how-do-i-authenticate-my-requests). ## Monetization of Actors in Standby mode diff --git a/sources/platform/actors/development/programming_interface/environment_variables.md b/sources/platform/actors/development/programming_interface/environment_variables.md index 572bf59d2e..4c0ec103de 100644 --- a/sources/platform/actors/development/programming_interface/environment_variables.md +++ b/sources/platform/actors/development/programming_interface/environment_variables.md @@ -54,7 +54,7 @@ Variables prefixed with `ACTOR_` are defined by the [Actor specification](https: | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. | | `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. Each run gets its own URL, which stops working when the run finishes. | | `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. The server also receives messages from the [Actor Standby](/actors/development/programming-interface/standby) mode. | -| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, it stays the same for all runs of the Actor, so you can share it publicly. | +| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, it stays the same for all runs of the Actor and can be shared publicly. | | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/actors/development/programming-interface/system-events) from Actor platform. | | `ACTOR_MCP_CONNECTOR_BASE_URL` | Base URL of the Apify MCP Proxy. Connect to an [MCP connector](/integrations/mcp-connectors) at `${ACTOR_MCP_CONNECTOR_BASE_URL}/` using `APIFY_TOKEN` as the bearer token. | From 80469b0da7290e2e21b7a6f509eccf3675cba4fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 17:11:37 +0200 Subject: [PATCH 05/10] docs: clarify where callers get the standby URL and tighten link text --- .../development/programming_interface/actor_standby.md | 6 +++--- .../programming_interface/environment_variables.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index f89ca5fa92..f760d87b90 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -172,13 +172,13 @@ async def main() -> None: ## Run lifecycle in Standby mode -The platform starts and stops Standby runs automatically based on the incoming request load. It stops a run that receives no requests within the configured idle timeout and starts a new run when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [dataset or key-value store](../../../storage/index.md). To learn how scaling works and how to configure the idle timeout, see the [scaling](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration) sections. +The platform starts and stops Standby runs automatically based on the incoming request load. It stops a run that receives no requests within the configured idle timeout and starts a new run when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [dataset or key-value store](../../../storage/index.md). See [how Standby scaling works](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [how to customize the Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration). ## Timeouts When you send a request to an Actor in Standby mode, the total timeout for receiving the first response is _5 minutes_. Before the platform forwards the request to a specific Actor run, it performs a _run selection_ process to determine the specific Actor run that will handle it. This process has internal timeout of _2 minutes_. -## Getting the URL of the Standby Actor +## Get the URL of the Standby Actor The URL is exposed as an environment variable `ACTOR_STANDBY_URL`. You can also use `Actor.config`, where the `standbyUrl` option is available. @@ -188,7 +188,7 @@ The URL typically combines the Actor owner's username and the Actor name, for ex https://jane-doe--my-actor.apify.actor ``` -Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor. Some Actors use a different hostname format, so always read the URL from the environment variable or the SDK configuration rather than building it yourself. +Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor: copy it from the **Standby** tab on the Actor's detail page rather than building it from the username and Actor name, because some Actors use a different hostname format. Requests to the Standby URL require an Apify API token. See [how to authenticate your requests](../../running/actor_standby.md#how-do-i-authenticate-my-requests). diff --git a/sources/platform/actors/development/programming_interface/environment_variables.md b/sources/platform/actors/development/programming_interface/environment_variables.md index 4c0ec103de..05f3c1ad33 100644 --- a/sources/platform/actors/development/programming_interface/environment_variables.md +++ b/sources/platform/actors/development/programming_interface/environment_variables.md @@ -54,7 +54,7 @@ Variables prefixed with `ACTOR_` are defined by the [Actor specification](https: | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. | | `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. Each run gets its own URL, which stops working when the run finishes. | | `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. The server also receives messages from the [Actor Standby](/actors/development/programming-interface/standby) mode. | -| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, it stays the same for all runs of the Actor and can be shared publicly. | +| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, it stays the same for all runs of the Actor, so it's safe to hardcode in calling applications. | | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/actors/development/programming-interface/system-events) from Actor platform. | | `ACTOR_MCP_CONNECTOR_BASE_URL` | Base URL of the Apify MCP Proxy. Connect to an [MCP connector](/integrations/mcp-connectors) at `${ACTOR_MCP_CONNECTOR_BASE_URL}/` using `APIFY_TOKEN` as the bearer token. | From d969bd1b8fe7fdc4554c47ab558481757075341d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 17:56:31 +0200 Subject: [PATCH 06/10] docs: point standby developers to the web server schema and MCP path --- .../development/programming_interface/actor_standby.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index f760d87b90..7b0c450c44 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -66,8 +66,7 @@ async def main() -> None: -Please make sure to describe your Actors, their endpoints, and the schema for their -inputs and outputs in your README. +Describe your Actor's endpoints, their parameters, and responses with a [web server schema](../actor_definition/web_server_schema/index.md) defined in the [`.actor/actor.json`](../actor_definition/actor_json.md) file. Apify Console then renders an interactive **Standby** tab on the Actor's detail page, where users can browse the endpoints and send requests directly from the browser. Describe the endpoints in your Actor's README as well. ### Readiness probe @@ -190,6 +189,8 @@ https://jane-doe--my-actor.apify.actor Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor: copy it from the **Standby** tab on the Actor's detail page rather than building it from the username and Actor name, because some Actors use a different hostname format. +If the Actor exposes an MCP server, its endpoint is the Standby URL followed by the path defined in the [`webServerMcpPath`](../actor_definition/actor_json.md) property. + Requests to the Standby URL require an Apify API token. See [how to authenticate your requests](../../running/actor_standby.md#how-do-i-authenticate-my-requests). ## Monetization of Actors in Standby mode From 7c74fe863023ada821b61b2e3d4f42af1652e813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 2 Sep 2026 17:56:31 +0200 Subject: [PATCH 07/10] docs: cross-link the web server schema from neighbor pages --- .../platform/actors/development/actor_definition/actor_json.md | 2 +- sources/platform/actors/development/actor_definition/index.md | 1 + .../development/programming_interface/container_web_server.md | 2 ++ sources/platform/actors/running/actor_standby.md | 1 + 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/sources/platform/actors/development/actor_definition/actor_json.md b/sources/platform/actors/development/actor_definition/actor_json.md index 17ce38afeb..5656258b68 100644 --- a/sources/platform/actors/development/actor_definition/actor_json.md +++ b/sources/platform/actors/development/actor_definition/actor_json.md @@ -93,5 +93,5 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `minMemoryMbytes` | Optional | Specifies the minimum amount of memory in megabytes required by the Actor to run. Requires an _integer_ value. If both `minMemoryMbytes` and `maxMemoryMbytes` are set, then `minMemoryMbytes` must be equal or lower than `maxMemoryMbytes`. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `maxMemoryMbytes` | Optional | Specifies the maximum amount of memory in megabytes required by the Actor to run. It can be used to control the costs of run. Requires an _integer_ value. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `usesStandbyMode` | Optional | Boolean specifying whether the Actor will have [Standby mode](../programming_interface/actor_standby.md) enabled. | -| `webServerSchema` | Optional | The `webServerSchema` property defines an OpenAPI v3 schema for the web server running in the Actor. Set the property to an embedded OpenAPI schema object or a path to a JSON schema file. Define the schema when your Actor starts its own HTTP server and you want to describe its interface. | +| `webServerSchema` | Optional | The `webServerSchema` property defines an OpenAPI v3 schema for the web server running in the Actor. Set the property to an embedded OpenAPI schema object or a path to a JSON schema file. Define the schema when your Actor starts its own HTTP server and you want to describe its interface. See [Actor web server schema](./web_server_schema/index.md). | | `webServerMcpPath` | Optional | The HTTP endpoint path where the Actor exposes its MCP (Model Context Protocol) server functionality. When set, the Actor is recognized as an MCP server. For example, setting `"/mcp"` designates the `/mcp` endpoint as the MCP interface. This path becomes part of the Actor's stable URL when [Standby mode](../programming_interface/actor_standby.md) is enabled. | diff --git a/sources/platform/actors/development/actor_definition/index.md b/sources/platform/actors/development/actor_definition/index.md index 01b0d1b46b..00cfca8fb9 100644 --- a/sources/platform/actors/development/actor_definition/index.md +++ b/sources/platform/actors/development/actor_definition/index.md @@ -15,6 +15,7 @@ Actors have the following elements: - **[Dockerfile](./docker.md)** which specifies where is the Actor's source code, how to build it, and run it. - **Documentation** in the form of a **README.md** file. - **[Input](./input_schema/index.md)** and **[output](./output_schema/index.md)** schemas that describe what input the Actor requires and what output it produces. +- **[Web server schema](./web_server_schema/index.md)** that describes the HTTP endpoints of the Actor's web server, if it runs one. - Access to an out-of-box **[storage](../../../storage/index.md)** system for Actor data, results, and files. The documentation and the input and output schemas make it possible for people to easily understand what the Actor does, enter the required inputs both in the user interface or API, and integrate the Actor's results with their other workflows. Actors can easily call and interact with each other, enabling building more complex systems on top of simple ones. diff --git a/sources/platform/actors/development/programming_interface/container_web_server.md b/sources/platform/actors/development/programming_interface/container_web_server.md index f9f12ec560..e33fc7244a 100644 --- a/sources/platform/actors/development/programming_interface/container_web_server.md +++ b/sources/platform/actors/development/programming_interface/container_web_server.md @@ -37,6 +37,8 @@ The web server inside the container must listen on the port specified by the `AC Check out [Custom environment variables](./environment_variables.md) for more details. +You can describe the web server's API with a [web server schema](../actor_definition/web_server_schema/index.md) in the Actor definition. + ## Example: Start a simple web server diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index bd87983cb4..9d7c194543 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -15,6 +15,7 @@ in the background, waiting for the incoming HTTP requests. In a sense, the Actor You will know that the Actor is enabled for Standby mode if you see the **Standby** tab on the Actor's detail page. In the tab, you will find the hostname of the server, the description of the Actor's endpoints, the parameters they accept, and what they return in the Actor README. +If the Actor defines a [web server schema](../development/actor_definition/web_server_schema/index.md), the tab also shows an interactive list of its endpoints, where you can send requests directly from the browser. To use the Actor in Standby mode, you don't need to click a start button or not need to do anything else. Simply use the provided hostname and endpoint in your application, hit the API endpoint and get results. From 9c7d2fb7ef49f2b61a99288002cd8ffdda6a4b1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 4 Sep 2026 14:32:46 +0200 Subject: [PATCH 08/10] docs: document that Standby runs get no health checks after readiness Supersedes #2577, which is stale against master. Its "a run only restarts on process exit or migration" wording is reconciled here with idle-timeout termination. --- .../development/programming_interface/actor_standby.md | 2 ++ sources/platform/actors/running/actor_standby.md | 6 ++++++ 2 files changed, 8 insertions(+) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index 7b0c450c44..c916d0ea5b 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -173,6 +173,8 @@ async def main() -> None: The platform starts and stops Standby runs automatically based on the incoming request load. It stops a run that receives no requests within the configured idle timeout and starts a new run when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [dataset or key-value store](../../../storage/index.md). See [how Standby scaling works](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [how to customize the Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration). +Apart from the [readiness probe](#readiness-probe), the platform doesn't check your server's health while the run is alive. A run ends when its process exits, when it migrates to another machine, or when it stays idle for longer than the idle timeout. A server that stays up but stops responding keeps receiving requests, so on an unrecoverable error, exit the process instead of swallowing the error. + ## Timeouts When you send a request to an Actor in Standby mode, the total timeout for receiving the first response is _5 minutes_. Before the platform forwards the request to a specific Actor run, it performs a _run selection_ process to determine the specific Actor run that will handle it. This process has internal timeout of _2 minutes_. diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 9d7c194543..11b925ccba 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -64,6 +64,12 @@ it well. Please head to the Actor README to learn more about the capabilities of When you use the Actor in Standby mode, the system automatically scales the Actor to accommodate the incoming requests. Under the hood, the system starts new Actor runs, which you will see in the Actor runs tab, with the origin set to Standby. +## Does the platform check that Standby runs are healthy + +The platform checks a run's readiness once, before the run starts serving requests, and performs no health checks after that. A run ends when its process exits, when it migrates to another machine, or when it stays idle for longer than the idle timeout. + +If an Actor's server stays up but stops responding, the platform doesn't detect the failure, and requests keep going to that run. To learn how to handle this in your own Actors, see [Develop Actors in Standby mode](../development/programming_interface/actor_standby.md#run-lifecycle-in-standby-mode). + ## What is the timeout for incoming requests For requests sent to an Actor in Standby mode, the maximum time allowed until receiving the first response is _5 minutes_. This represents the overall timeout for the operation. From a248057cc1d528e4dcbee4bb8be57f70bbe91987 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 4 Sep 2026 14:50:06 +0200 Subject: [PATCH 09/10] docs: document the ID-based standby URL and correct the Console tab name --- .../development/programming_interface/actor_standby.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index c916d0ea5b..595d8b675f 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -66,7 +66,7 @@ async def main() -> None: -Describe your Actor's endpoints, their parameters, and responses with a [web server schema](../actor_definition/web_server_schema/index.md) defined in the [`.actor/actor.json`](../actor_definition/actor_json.md) file. Apify Console then renders an interactive **Standby** tab on the Actor's detail page, where users can browse the endpoints and send requests directly from the browser. Describe the endpoints in your Actor's README as well. +Describe your Actor's endpoints, their parameters, and responses with a [web server schema](../actor_definition/web_server_schema/index.md) defined in the [`.actor/actor.json`](../actor_definition/actor_json.md) file. Apify Console then renders an interactive **Endpoints** tab on the Actor's detail page, where users can browse the endpoints and send requests directly from the browser. Describe the endpoints in your Actor's README as well. ### Readiness probe @@ -189,7 +189,13 @@ The URL typically combines the Actor owner's username and the Actor name, for ex https://jane-doe--my-actor.apify.actor ``` -Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor: copy it from the **Standby** tab on the Actor's detail page rather than building it from the username and Actor name, because some Actors use a different hostname format. +The Actor also responds on a URL built from its ID, which keeps working if the Actor or its owner is renamed: + +```text +https://92c4oi4fpzy7rprlf.apify.actor +``` + +Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor: copy it from the **Endpoints** tab on the Actor's detail page rather than building it from the username and Actor name, because some Actors use a different hostname format. If the Actor exposes an MCP server, its endpoint is the Standby URL followed by the path defined in the [`webServerMcpPath`](../actor_definition/actor_json.md) property. From 63364fdf31932541c710caa358c75c7f5a963165 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 4 Sep 2026 14:50:06 +0200 Subject: [PATCH 10/10] docs: rename the Standby tab to Endpoints Apify Console renders this tab as Endpoints for both Actors and Tasks; no Standby tab exists any more. The screenshots still show the old label and need recapturing separately. --- .../apify_actors/adding_rapidapi_project.md | 2 +- .../actor_definition/web_server_schema/index.md | 12 ++++++------ sources/platform/actors/running/actor_standby.md | 8 ++++---- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md b/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md index 41bda37656..4a2f70b839 100644 --- a/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md +++ b/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md @@ -114,7 +114,7 @@ Actors can run in two modes: as batch processing jobs that execute a single task ::: -Once you’ve saved the settings, go to the **Standby** tab, and click the **Test endpoint** button. It will start the Actor, and you can test it. Once the Actor is running, you're done with the migration! +Once you’ve saved the settings, go to the **Endpoints** tab, and click the **Test endpoint** button. It will start the Actor, and you can test it. Once the Actor is running, you're done with the migration! ## Next steps diff --git a/sources/platform/actors/development/actor_definition/web_server_schema/index.md b/sources/platform/actors/development/actor_definition/web_server_schema/index.md index 1e52330e26..d5f1a0f839 100644 --- a/sources/platform/actors/development/actor_definition/web_server_schema/index.md +++ b/sources/platform/actors/development/actor_definition/web_server_schema/index.md @@ -2,13 +2,13 @@ title: Actor web server schema sidebar_label: Web server schema sidebar_position: 7 -description: Attach an OpenAPI specification to your Actor to enable the interactive Standby tab in Apify Console and Apify Store, where you can browse and test endpoints. +description: Attach an OpenAPI specification to your Actor to enable the interactive Endpoints tab in Apify Console and Apify Store, where you can browse and test endpoints. slug: /actors/development/actor-definition/web-server-schema --- -The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Standby** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser. +The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Endpoints** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser. -![Apify Console showing the Standby tab with the Endpoints section rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) +![Apify Console showing the Endpoints tab rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) ## Define the web server schema @@ -92,7 +92,7 @@ Follow the standard [OpenAPI 3.x format](https://spec.openapis.org/oas/latest.ht The build process validates `webServerSchema`, similar to other Actor schemas like [input schema](/actors/development/actor-definition/input-schema) and [dataset schema](/storage/dataset-schema). If the spec is malformed, the build fails with a validation error. -Once deployed, the **Standby** tab appears automatically on the Actor's detail page when you enable [standby mode](/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens. +Once deployed, the **Endpoints** tab appears automatically on the Actor's detail page when you enable [standby mode](/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens. :::note Servers field is overwritten @@ -104,5 +104,5 @@ Your `servers` array is replaced with the Actor's standby URL at display time. C | Field | Description | | --- | --- | -| `usesStandbyMode` | Must be `true` for the **Standby** tab to appear. See [standby mode](/actors/development/programming-interface/standby). | -| `webServerSchema` | The OpenAPI spec that powers the **Standby** tab. Defined in [`.actor/actor.json`](/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. | +| `usesStandbyMode` | Must be `true` for the **Endpoints** tab to appear. See [standby mode](/actors/development/programming-interface/standby). | +| `webServerSchema` | The OpenAPI spec that powers the **Endpoints** tab. Defined in [`.actor/actor.json`](/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. | diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 11b925ccba..ae2f916202 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -12,7 +12,7 @@ in the background, waiting for the incoming HTTP requests. In a sense, the Actor ## How do I know if Standby mode is enabled -You will know that the Actor is enabled for Standby mode if you see the **Standby** tab on the Actor's detail page. +You will know that the Actor is enabled for Standby mode if you see the **Endpoints** tab on the Actor's detail page. In the tab, you will find the hostname of the server, the description of the Actor's endpoints, the parameters they accept, and what they return in the Actor README. If the Actor defines a [web server schema](../development/actor_definition/web_server_schema/index.md), the tab also shows an interactive list of its endpoints, where you can send requests directly from the browser. @@ -20,7 +20,7 @@ If the Actor defines a [web server schema](../development/actor_definition/web_s To use the Actor in Standby mode, you don't need to click a start button or not need to do anything else. Simply use the provided hostname and endpoint in your application, hit the API endpoint and get results. -![Standby tab](./images/actor_standby/standby-tab.png) +![Endpoints tab](./images/actor_standby/standby-tab.png) ## How do I pass input to Actors in Standby mode @@ -88,9 +88,9 @@ The Standby configuration currently consists of the following properties: - **Idle timeout (seconds)** - If a Standby Actor run doesn’t receive any HTTP requests within this time, the system will terminate the run. When a new request arrives, the system might need to start a new Standby Actor run to handle it, which can take a few seconds. A higher idle timeout improves responsiveness but increases costs, as the Actor remains active for a longer period. - **Build** - The Actor build that the runs of the Standby Actor will use. Can be either a build tag (e.g. `latest.`), or a build number (e.g. `0.1.2`). -You can see these in the Standby tab of the Actor detail page. However, note that these properties are not configurable at the Actor level. If you wish to +You can see these in the **Endpoints** tab of the Actor detail page. However, note that these properties are not configurable at the Actor level. If you wish to use the Actor-level hostname, this will always use the default configuration. To override this configuration, just create a new Task from the Actor. -You can then head to the Standby tab of the created Task and modify the configuration as needed. Note that the task has a specific hostname, so make +You can then head to the **Endpoints** tab of the created Task and modify the configuration as needed. Note that the task has a specific hostname, so make sure to use that in your application if you wish to use the custom configuration. ## Are the Standby runs billed differently