From 87b471bcf2c5a306eb5822358a2a8c2dbfb4774b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 16 Sep 2026 21:39:35 +0200 Subject: [PATCH 1/5] docs: restructure Standby pages with topic-based headings Replaces the FAQ-style question headings with the topic structure used by sibling pages, moves the Standby URL section to the user page, and gives each duplicated fact a single owner with cross-links. --- .../programming_interface/actor_standby.md | 116 ++++++++--------- .../platform/actors/running/actor_standby.md | 123 +++++++++++------- 2 files changed, 133 insertions(+), 106 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index 345b07e281..9b49046b1a 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -6,33 +6,49 @@ slug: /actors/development/programming-interface/standby sidebar_position: 9 --- -Traditional Actors are designed to run a single task and then stop. They're mostly intended for batch jobs, such as when you need to perform a large scrape or data processing task. -However, in some applications, waiting for an Actor to start is not an option. Actor Standby mode solves this problem by letting you have the Actor ready -in the background, waiting for the incoming HTTP requests. In a sense, the Actor behaves like a real-time web server or standard API server. - -## Developing Actors using Standby mode - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -The best way to start developing Standby Actors is to use the predefined templates in the [Console UI](https://console.apify.com/actors/templates) or in [CLI](https://docs.apify.com/cli/) via `apify create`. The templates contain minimal code to get you up to speed for development in JavaScript, TypeScript or Python. Standby mode will automatically be enabled with default settings. +While a traditional Actor runs a single job and stops, an Actor in Standby mode runs a persistent HTTP server and responds to incoming requests in real time. For the user-facing overview of Standby mode, including endpoints, authentication, scaling, configuration, and billing, see [Actor Standby mode](../../running/actor_standby.md). + +## Enable Standby mode + +You can enable Standby mode from a template, in Apify Console, or in the Actor's source code. + +### Start from a template + +The best way to start developing Standby Actors is to use the predefined templates in [Apify Console](https://console.apify.com/actors/templates) or in the [Apify CLI](https://docs.apify.com/cli/) via `apify create`. The templates contain minimal code to get you up to speed for development in JavaScript, TypeScript, or Python. Standby mode will automatically be enabled with default settings. + +### Enable Standby in Apify Console + +To enable or tweak Standby mode for an existing Actor, head to the **Settings** tab of your Actor, where the Actor Standby settings are located. -If you already have an existing Actor, or you just want to tweak the configuration of Standby mode, you can head to the Settings tab of your Actor, where the Actor Standby settings are located. -![Standby for creators](./images/standby-creators.png) +![Standby settings in the Actor's Settings tab](./images/standby-creators.png) -You can also enable Standby mode from the Actor's source code by setting the [`usesStandbyMode`](../actor_definition/actor_json.md) property to `true` in the `.actor/actor.json` file. When you push the Actor with the [Apify CLI](https://docs.apify.com/cli/), the setting syncs to the platform. +If you want to enforce the same Standby configuration for all users of your Actor, enable **Prevent users from overriding standby parameters** in the same settings. Users then can't override the configuration by creating a task. -Actors using Standby mode must run a HTTP server listening on a specific port. The user requests will then be proxied to the HTTP server. You can use any of the existing [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) like GET, POST, PUT, DELETE, etc. You can pass the input via [HTTP request query string](https://en.wikipedia.org/wiki/Query_string) or via [HTTP request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). +### Enable Standby in the source code -Sometimes, you want the HTTP server to listen on a specific port and cannot change it yourself. You can use `ACTOR_WEB_SERVER_PORT` environment variable to override the port so that Actor Standby will work with your code. +You can also enable Standby mode by setting the [`usesStandbyMode`](../actor_definition/actor_json.md) property to `true` in the `.actor/actor.json` file. When you push the Actor with the [Apify CLI](https://docs.apify.com/cli/), the setting syncs to the platform. -You can get the port using the Actor configuration available in Apify SDK. -See example below with a simple Actor using Standby mode. +## Run an HTTP server + +Actors using Standby mode must run an HTTP server listening on a specific port. The platform proxies user requests to that server. The requests can use any of the existing [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), such as GET, POST, PUT, or DELETE, and pass input via the [query string](https://en.wikipedia.org/wiki/Query_string) or the [request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). + +### Get the port + +The server must listen on the port defined by the `ACTOR_WEB_SERVER_PORT` environment variable. If you use the Apify SDK, read the port from the Actor configuration instead: the option is named `containerPort` in JavaScript and `web_server_port` in Python. + +If your server must listen on a specific port that you can't change in code, define `ACTOR_WEB_SERVER_PORT` as a custom [environment variable](./environment_variables.md) of the Actor, with that port as the value. The platform then proxies the requests to your port. + +### Example server + +See the example below with a simple Actor using Standby mode. -```js +```javascript import http from 'http'; import { Actor } from 'apify'; @@ -68,25 +84,31 @@ async def main() -> None: +## Describe your endpoints + 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. Based on that definition, Apify Console 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](../../publishing/publish/actor-readme.mdx) as well, because that's what users see in Apify Store before they ever open the Actor's detail page. +## Run lifecycle + +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#automatic-scaling), [how to customize the Standby configuration](../../running/actor_standby.md#standby-configuration), and [the timeouts and rate limits](../../running/actor_standby.md#limits-and-scaling) that apply to incoming requests. + ### Readiness probe -Before Actor standby runs are ready to serve requests, the Apify platform checks the web server's readiness using a readiness probe. +Before Actor Standby runs are ready to serve requests, the Apify platform checks the web server's readiness using a readiness probe. The platform sends a GET request to the path `/` with a header `x-apify-container-server-readiness-probe`. If the header is present in the request, you can perform an early return with a simple response to prevent wasting resources. -:::note Return a response +:::caution Return a response You must return a response; otherwise, the Actor run will never be marked as ready and won't process requests. ::: -See example code below that distinguishes between "normal" and "readiness probe" requests. +See the example code below that distinguishes between "normal" and "readiness probe" requests. -```js +```javascript import http from 'http'; import { Actor } from 'apify'; @@ -133,16 +155,20 @@ async def main() -> None: -## Determining an Actor is started in Standby +### Run termination + +A run ends when its process exits, when it migrates to another machine, or when it stays idle for longer than the idle timeout. Apart from the [readiness probe](#readiness-probe), the platform doesn't check your server's health while the run is alive. A server that stays up but stops responding keeps receiving requests, so on an unrecoverable error, exit the process instead of swallowing the error. -Actors that support Actor Standby can still be started in standard mode, for example from the Console or via the API. -To find out in which mode was the Actor started, you can read the `metaOrigin` option in `Actor.config`, or the `APIFY_META_ORIGIN` environment variable in case you're not using the Apify SDK. -If it is equal to `STANDBY`, the Actor was started in Standby mode, otherwise it was started in standard mode. +## Detect the run mode + +Actors that support Actor Standby can still be started in standard mode, for example from Apify Console or via the API. +To find out which mode the Actor was started in, read the `metaOrigin` option in `Actor.config`, or the `APIFY_META_ORIGIN` environment variable in case you're not using the Apify SDK. +If it equals `STANDBY`, the Actor was started in Standby mode; otherwise it was started in standard mode. -```js +```javascript import { Actor } from 'apify'; await Actor.init(); @@ -163,48 +189,22 @@ from apify import Actor async def main() -> None: async with Actor: if Actor.configuration.meta_origin == 'STANDBY': - # Start your Standby server here + ... # Start your Standby server here else: - # Perform the standard Actor operations here + ... # Perform the standard Actor operations here ``` -## 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). 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_. - -## 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. - -The URL typically combines the Actor owner's username and the Actor name, for example: - -```text -https://jane-doe--my-actor.apify.actor -``` - -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. Don't build the URL from the username and Actor name, because some Actors use a different hostname format. +## Standby URL -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. +Each Standby Actor has a URL that stays the same for all of its runs. The URL is exposed as the `ACTOR_STANDBY_URL` environment variable and as the `standbyUrl` option in `Actor.config`. -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). +Unlike the Standby URL, the [container web server](./container_web_server.md) URL changes with every run. For the URL formats and where users find them, see [Standby URLs](../../running/actor_standby.md#standby-urls). -## Monetization of Actors in Standby mode +Requests to the Standby URL require an Apify API token; see [how to authenticate requests](../../running/actor_standby.md#authenticate-requests). If your Actor exposes an MCP server, define the endpoint path with the [`webServerMcpPath`](../actor_definition/actor_json.md) property; see [Use Standby Actors as MCP servers](../../running/actor_standby.md#use-standby-actors-as-mcp-servers). -You can monetize Standby Actors just like any other Actor. +## Monetize Standby Actors -For best results with Standby workflows, use the [pay-per-event pricing model](/actors/monetize/pay-per-event). In this model, users cover both the platform usage costs of their runs, as well as the event costs. +You can monetize Standby Actors just like any other Actor. For best results with Standby workflows, use the [pay-per-event pricing model](/actors/monetize/pay-per-event). In this model, users cover both the platform usage costs of their runs and the event costs. diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 0ae933cde5..8a2e3d6096 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -10,37 +10,52 @@ Traditional Actors are designed to run a single job and then stop. They're mostl However, in some applications, waiting for an Actor to start is not an option. Actor Standby mode solves this problem by letting you have the Actor ready in the background, waiting for the incoming HTTP requests. In a sense, the Actor behaves like a real-time web server or standard API server. -## How do I know if Standby mode is enabled +To build your own Standby Actor, see [Develop Actors in Standby mode](../development/programming_interface/actor_standby.md). -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. +## Check whether an Actor supports Standby mode + +If an Actor has Standby mode enabled, its detail page shows the **Endpoints** tab. The tab contains the hostname of the Actor's server, and the Actor README describes the endpoints, the parameters they accept, and what they return. 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. +To use the Actor in Standby mode, you don't need to start the Actor or do anything else. Send a request to the provided hostname and endpoint, and you get the results. + +![Endpoints tab on the Actor detail page](./images/actor_standby/standby-tab.png) + +## Standby URLs + +The Standby URL typically combines the Actor owner's username and the Actor name, for example: + +```text +https://jane-doe--my-actor.apify.actor +``` -![Endpoints tab](./images/actor_standby/standby-tab.png) +The Actor also responds on a URL built from its ID, which keeps working if the Actor or its owner is renamed: -## How do I pass input to Actors in Standby mode +```text +https://92c4oi4fpzy7rprlf.apify.actor +``` -If you're using an Actor built by someone else, see its Information tab to find out how the input should be passed. +The Standby URL stays the same for all runs of the Actor, so you can share it publicly or hardcode it in applications that call the Actor. Copy the URL from the **Endpoints** tab instead of building it from the username and Actor name, because some Actors use a different hostname format, like `rag-web-browser.apify.actor` in the examples below. -Generally speaking, Actors in Standby mode behave as standard HTTP servers. You can use any of the existing [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) like GET, POST, PUT, DELETE, etc. You can pass the input via [HTTP request query string](https://en.wikipedia.org/wiki/Query_string) or via [HTTP request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). +## Send requests to the Actor -## How do I authenticate my requests +If you're using an Actor built by someone else, see its **Readme** tab to find out how to pass the input. + +Generally speaking, Actors in Standby mode behave as standard HTTP servers. Use any of the existing [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), such as GET, POST, PUT, or DELETE, and pass the input via the [query string](https://en.wikipedia.org/wiki/Query_string) or the [request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). + +## Authenticate requests To authenticate requests to Actor Standby, follow the same process as [authenticating requests to the Apify API](../../integrations/programming/api.md). You can provide your [API token](../../integrations/programming/api.md#api-token) in one of two ways: 1. _Recommended_: Include the token in the `Authorization` header of your request as `Bearer `. This approach is recommended because it prevents your token from being logged in server logs. - ```shell + ```bash curl -H "Authorization: Bearer my_apify_token" \ https://rag-web-browser.apify.actor/search?query=apify ``` -2. Append the token as a query parameter named `token` to the request URL. +1. Append the token as a query parameter named `token` to the request URL. This approach can be useful if you cannot modify the request headers. ```text @@ -51,70 +66,82 @@ The platform removes the token from the request before forwarding it, so the tok If you're developing a Standby Actor, use the token from the `APIFY_TOKEN` [environment variable](../development/programming_interface/environment_variables.md#system-environment-variables) to call the Apify API, as in any other Actor. -:::tip Scoped tokens -You can use [scoped tokens](/integrations/api#limited-permissions) to send standby requests. This is useful for allowing third-party services to interact with your Actor without granting access to your entire account. +If you want to let third-party services interact with your Actor without granting access to your entire account, use [scoped tokens](/integrations/api#limited-permissions) to send Standby requests. + +:::caution Restricted access is not supported + +[Restricting what an Actor can access](/integrations/api#restricted-access-restrict-what-actors-can-access-using-the-scope-of-this-actor) using a scoped token is not supported when running in Standby mode. -However, [restricting what an Actor can access](/integrations/api#restricted-access-restrict-what-actors-can-access-using-the-scope-of-this-actor) using a scoped token is not supported when running in Standby mode. ::: -## Can I still run the Actor in normal mode +## Run the Actor in normal mode -Yes, you can still modify the input and click the Start button to run the Actor in normal mode. However, note that the Standby Actor might -not support this mode; the run might fail or return empty results. The normal mode is always supported in Standby Beta, even for Actors that don't handle -it well. Please head to the Actor README to learn more about the capabilities of your chosen Actor. +You can still modify the input and select **Start** to run the Actor in normal mode. However, the Standby Actor might not support it; the run might fail or return empty results. The platform always allows starting the run, even for Actors that don't handle the normal mode well. Head to the Actor README to learn about the capabilities of your chosen Actor. -## Is there any scaling to accommodate the incoming requests +## Limits and scaling + +The platform scales Standby runs automatically and applies timeouts and rate limits to the incoming requests. + +### Automatic scaling 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. +the system starts new Actor runs, which you will see in the Actor **Runs** tab, with the origin set to Standby. + +The background runs that serve your requests are not shared with other users, even if you use the Actor-level hostname with the default configuration. -## 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. -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. +:::caution Unresponsive servers aren't detected -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). +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 [Run lifecycle](../development/programming_interface/actor_standby.md#run-lifecycle). + +::: -## What is the timeout for incoming requests +### Request timeouts 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. Within this window, the platform first selects an Actor run to handle the request, which can take up to _2 minutes_, for example when a new run needs to start. If no run becomes available within that time, the request fails with a `429` error. -## What is the rate limit for incoming requests +### Rate limits Incoming requests to Standby Actors are rate-limited per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a `429` error. -## How do I customize Standby configuration +## Standby configuration -The Standby configuration currently consists of the following properties: +The Standby configuration consists of the following properties: -- **Max requests per run** - The maximum number of concurrent HTTP requests a single Standby Actor run can accept. If this limit is exceeded, the system starts a new Actor run to handle the request, which may take a few seconds. -- **Desired requests per run** - The number of concurrent HTTP requests a single Standby Actor run is configured to handle. If this limit is exceeded, the system preemptively starts a new Actor run to handle the additional requests. -- **Memory (MB)** - The amount of memory (RAM) allocated for the Actor in Standby mode, in megabytes. With more memory, the Actor can typically handle more requests in parallel, but this also increases the number of compute units consumed and the associated cost. -- **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`). +| Property | Description | +| --- | --- | +| Max requests per run | The maximum number of concurrent HTTP requests a single Standby Actor run can accept. If this limit is exceeded, the system starts a new Actor run to handle the request, which may take a few seconds. | +| Desired requests per run | The number of concurrent HTTP requests a single Standby Actor run is configured to handle. If this limit is exceeded, the system preemptively starts a new Actor run to handle the additional requests. | +| Memory (MB) | The amount of memory (RAM) allocated for the Actor in Standby mode, in megabytes. With more memory, the Actor can typically handle more requests in parallel, but this also increases the number of compute units consumed and the associated cost. | +| Idle timeout (seconds) | If a Standby Actor run doesn't receive any HTTP requests within this time, the system terminates 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 **Endpoints** tab of the Actor detail page. If you own the Actor, you can change its default Standby configuration in the **Settings** tab. +You can see the current values in the **Endpoints** tab of the Actor detail page. If you own the Actor, you can change its default Standby configuration in the **Settings** tab. -If you use an Actor built by someone else, the Actor-level hostname always uses the developer's default configuration. To override it, create a new Task from the Actor. -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. The Actor's developer can lock the Standby configuration. In that case, the task-level settings have no effect. +### Override the configuration with a task -## Are the Standby runs billed differently +If you use an Actor built by someone else, the Actor-level hostname always uses the developer's default configuration. To override it: -No, the Standby runs are billed in the same fashion as the normal runs. -However, running Actors in Standby mode might have unexpected costs, as the Actors run in the background and consume resources even when no requests are being sent until they are terminated after the idle timeout period. +1. In [Apify Console](https://console.apify.com), create a new task from the Actor. +1. Open the **Endpoints** tab of the created task. +1. Modify the configuration as needed. +1. In your application, use the task's hostname instead of the Actor's. -For Actors monetized with the [pay-per-event pricing model](/actors/monetize/pay-per-event), you pay the platform usage costs of the Standby runs in addition to the event charges. +:::note Developers can lock the configuration + +The Actor's developer can lock the Standby configuration. In that case, the task-level settings have no effect. -## Are the Standby runs shared among users +::: -No, even if you use the Actor-level hostname with the default configuration, the background Actor runs for your requests are not shared with other users. +## Billing -## Can I use Standby Actors as MCP servers +Standby runs are billed in the same fashion as normal runs. However, they might have unexpected costs. The Actors run in the background and consume resources even when no requests arrive, until the idle timeout terminates them. -Yes, if the Actor exposes a [Model Context Protocol (MCP)](../../agents/mcp.md) server. Its MCP endpoint is the Standby hostname followed by the path defined in the Actor's [`webServerMcpPath`](../development/actor_definition/actor_json.md) property. Authenticate requests to the MCP endpoint the same way as any other Standby request. +For Actors monetized with the [pay-per-event pricing model](/actors/monetize/pay-per-event), you pay the platform usage costs of the Standby runs in addition to the event charges. -## How can I develop Actors using Standby mode +## Use Standby Actors as MCP servers -See the [Actor Standby development section](../development/programming_interface/actor_standby.md). +If the Actor exposes a [Model Context Protocol (MCP)](../../agents/mcp.md) server, its MCP endpoint is the Standby URL followed by the path defined in the Actor's [`webServerMcpPath`](../development/actor_definition/actor_json.md) property. Authenticate requests to the MCP endpoint the same way as any other Standby request. From 37d00ad45db03efa21ac74b3d4191a7ece957801 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Thu, 22 Oct 2026 16:37:07 +0200 Subject: [PATCH 2/5] docs: tighten the Standby pages Plain-language pass after the restructure: active voice, shorter sentences, one term per concept. Facts and structure unchanged. --- .../programming_interface/actor_standby.md | 25 +++++----- .../platform/actors/running/actor_standby.md | 47 +++++++++---------- 2 files changed, 32 insertions(+), 40 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index 9b49046b1a..8e6dedcd2f 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -17,15 +17,15 @@ You can enable Standby mode from a template, in Apify Console, or in the Actor's ### Start from a template -The best way to start developing Standby Actors is to use the predefined templates in [Apify Console](https://console.apify.com/actors/templates) or in the [Apify CLI](https://docs.apify.com/cli/) via `apify create`. The templates contain minimal code to get you up to speed for development in JavaScript, TypeScript, or Python. Standby mode will automatically be enabled with default settings. +The easiest way to start is a Standby template, in [Apify Console](https://console.apify.com/actors/templates) or with `apify create` in the [Apify CLI](https://docs.apify.com/cli/). The templates contain minimal JavaScript, TypeScript, or Python code, and Standby mode is enabled with default settings. ### Enable Standby in Apify Console -To enable or tweak Standby mode for an existing Actor, head to the **Settings** tab of your Actor, where the Actor Standby settings are located. +To enable or change Standby mode for an existing Actor, open the **Settings** tab of the Actor and find the Actor Standby settings. ![Standby settings in the Actor's Settings tab](./images/standby-creators.png) -If you want to enforce the same Standby configuration for all users of your Actor, enable **Prevent users from overriding standby parameters** in the same settings. Users then can't override the configuration by creating a task. +To enforce the same Standby configuration for all users of your Actor, enable **Prevent users from overriding standby parameters** in the same settings. Users then can't override it by creating a task. ### Enable Standby in the source code @@ -33,7 +33,7 @@ You can also enable Standby mode by setting the [`usesStandbyMode`](../actor_def ## Run an HTTP server -Actors using Standby mode must run an HTTP server listening on a specific port. The platform proxies user requests to that server. The requests can use any of the existing [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), such as GET, POST, PUT, or DELETE, and pass input via the [query string](https://en.wikipedia.org/wiki/Query_string) or the [request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). +A Standby Actor must run an HTTP server that listens on a specific port. The platform proxies user requests to that server. Requests can use any [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), such as GET, POST, PUT, or DELETE, and pass input in the [query string](https://en.wikipedia.org/wiki/Query_string) or the [request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). ### Get the port @@ -43,7 +43,7 @@ If your server must listen on a specific port that you can't change in code, def ### Example server -See the example below with a simple Actor using Standby mode. +The example below is a minimal Standby Actor. @@ -86,24 +86,23 @@ async def main() -> None: ## Describe your endpoints -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. Based on that definition, Apify Console 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](../../publishing/publish/actor-readme.mdx) as well, because that's what users see in Apify Store before they ever open the Actor's detail page. +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. Based on that definition, Apify Console 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](../../publishing/publish/actor-readme.mdx) as well, because users see the README in Apify Store before they open the Actor's detail page. ## Run lifecycle -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#automatic-scaling), [how to customize the Standby configuration](../../running/actor_standby.md#standby-configuration), and [the timeouts and rate limits](../../running/actor_standby.md#limits-and-scaling) that apply to incoming requests. +The platform starts and stops Standby runs based on the incoming request load. It stops a run that receives no requests within the 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). For details, see [how Standby scaling works](../../running/actor_standby.md#automatic-scaling), [how to customize the Standby configuration](../../running/actor_standby.md#standby-configuration), and [the timeouts and rate limits](../../running/actor_standby.md#limits-and-scaling) that apply to incoming requests. ### Readiness probe -Before Actor Standby runs are ready to serve requests, the Apify platform checks the web server's readiness using a readiness probe. -The platform sends a GET request to the path `/` with a header `x-apify-container-server-readiness-probe`. If the header is present in the request, you can perform an early return with a simple response to prevent wasting resources. +Before a Standby run serves requests, the platform checks that the web server is ready. It sends a GET request to the path `/` with the `x-apify-container-server-readiness-probe` header. When a request carries this header, you can return a simple response early to avoid wasting resources. :::caution Return a response -You must return a response; otherwise, the Actor run will never be marked as ready and won't process requests. +Always return a response. Otherwise, the platform never marks the run as ready, and it won't process requests. ::: -See the example code below that distinguishes between "normal" and "readiness probe" requests. +The example below tells normal requests from readiness probes. @@ -161,9 +160,7 @@ A run ends when its process exits, when it migrates to another machine, or when ## Detect the run mode -Actors that support Actor Standby can still be started in standard mode, for example from Apify Console or via the API. -To find out which mode the Actor was started in, read the `metaOrigin` option in `Actor.config`, or the `APIFY_META_ORIGIN` environment variable in case you're not using the Apify SDK. -If it equals `STANDBY`, the Actor was started in Standby mode; otherwise it was started in standard mode. +Users can still start a Standby Actor in standard mode, for example from Apify Console or through the API. To find out which mode the Actor started in, read the `metaOrigin` option in `Actor.config`, or the `APIFY_META_ORIGIN` environment variable if you don't use the Apify SDK. The value `STANDBY` means Standby mode. Otherwise, the Actor started in standard mode. diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 8a2e3d6096..293c993860 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -6,9 +6,7 @@ slug: /actors/running/standby sidebar_label: Standby mode --- -Traditional Actors are designed to run a single job and then stop. They're mostly intended for batch jobs, such as when you need to perform a large scrape or data processing task. -However, in some applications, waiting for an Actor to start is not an option. Actor Standby mode solves this problem by letting you have the Actor ready -in the background, waiting for the incoming HTTP requests. In a sense, the Actor behaves like a real-time web server or standard API server. +A traditional Actor runs a single job and then stops. That suits batch jobs, such as a large data extraction or processing task. Some applications can't wait for an Actor to start. In Standby mode, the Actor stays ready in the background and serves incoming HTTP requests in real time, like a web server or an API server. To build your own Standby Actor, see [Develop Actors in Standby mode](../development/programming_interface/actor_standby.md). @@ -17,7 +15,7 @@ To build your own Standby Actor, see [Develop Actors in Standby mode](../develop If an Actor has Standby mode enabled, its detail page shows the **Endpoints** tab. The tab contains the hostname of the Actor's server, and the Actor README describes the endpoints, the parameters they accept, and what they return. 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 start the Actor or do anything else. Send a request to the provided hostname and endpoint, and you get the results. +You don't need to start the Actor. Send a request to that hostname and endpoint, and you get the results. ![Endpoints tab on the Actor detail page](./images/actor_standby/standby-tab.png) @@ -39,24 +37,22 @@ The Standby URL stays the same for all runs of the Actor, so you can share it pu ## Send requests to the Actor -If you're using an Actor built by someone else, see its **Readme** tab to find out how to pass the input. +If you use an Actor built by someone else, its **Readme** tab describes how to pass the input. -Generally speaking, Actors in Standby mode behave as standard HTTP servers. Use any of the existing [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), such as GET, POST, PUT, or DELETE, and pass the input via the [query string](https://en.wikipedia.org/wiki/Query_string) or the [request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). +Actors in Standby mode behave as standard HTTP servers. Use any [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), such as GET, POST, PUT, or DELETE, and pass the input in the [query string](https://en.wikipedia.org/wiki/Query_string) or the [request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body). ## Authenticate requests -To authenticate requests to Actor Standby, follow the same process as [authenticating requests to the Apify API](../../integrations/programming/api.md). -You can provide your [API token](../../integrations/programming/api.md#api-token) in one of two ways: +Authenticate Standby requests the same way as [requests to the Apify API](../../integrations/programming/api.md). Provide your [API token](../../integrations/programming/api.md#api-token) in one of two ways: -1. _Recommended_: Include the token in the `Authorization` header of your request as `Bearer `. This approach is recommended because it prevents your token from being logged in server logs. +1. _Recommended_: Include the token in the `Authorization` header as `Bearer `. This keeps the token out of server logs. ```bash curl -H "Authorization: Bearer my_apify_token" \ https://rag-web-browser.apify.actor/search?query=apify ``` -1. Append the token as a query parameter named `token` to the request URL. -This approach can be useful if you cannot modify the request headers. +1. Append the token to the request URL as the `token` query parameter. Use this when you can't modify the request headers. ```text https://rag-web-browser.apify.actor/search?query=apify&token=my_apify_token @@ -66,17 +62,17 @@ The platform removes the token from the request before forwarding it, so the tok If you're developing a Standby Actor, use the token from the `APIFY_TOKEN` [environment variable](../development/programming_interface/environment_variables.md#system-environment-variables) to call the Apify API, as in any other Actor. -If you want to let third-party services interact with your Actor without granting access to your entire account, use [scoped tokens](/integrations/api#limited-permissions) to send Standby requests. +To let third-party services call your Actor without access to your entire account, send Standby requests with [scoped tokens](/integrations/api#limited-permissions). :::caution Restricted access is not supported -[Restricting what an Actor can access](/integrations/api#restricted-access-restrict-what-actors-can-access-using-the-scope-of-this-actor) using a scoped token is not supported when running in Standby mode. +Standby mode doesn't support [restricting what an Actor can access](/integrations/api#restricted-access-restrict-what-actors-can-access-using-the-scope-of-this-actor) with a scoped token. ::: ## Run the Actor in normal mode -You can still modify the input and select **Start** to run the Actor in normal mode. However, the Standby Actor might not support it; the run might fail or return empty results. The platform always allows starting the run, even for Actors that don't handle the normal mode well. Head to the Actor README to learn about the capabilities of your chosen Actor. +You can still modify the input and select **Start** to run the Actor in normal mode. The platform always allows it, but the Actor might not support it. The run might fail or return empty results. Check the Actor README for what the Actor supports. ## Limits and scaling @@ -84,10 +80,9 @@ The platform scales Standby runs automatically and applies timeouts and rate lim ### Automatic scaling -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. +The platform scales the Actor to match the incoming requests. It starts new Actor runs, which appear in the Actor **Runs** tab with the origin set to Standby. -The background runs that serve your requests are not shared with other users, even if you use the Actor-level hostname with the default configuration. +The runs that serve your requests aren't shared with other users, even when you use the Actor-level hostname with the default configuration. The platform checks a run's readiness once, before the run starts serving requests, and performs no health checks after that. @@ -99,25 +94,25 @@ If an Actor's server stays up but stops responding, the platform doesn't detect ### Request timeouts -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. +A request to a Standby Actor must receive its first response within _5 minutes_. This is the overall timeout for the request. Within this window, the platform first selects an Actor run to handle the request, which can take up to _2 minutes_, for example when a new run needs to start. If no run becomes available within that time, the request fails with a `429` error. ### Rate limits -Incoming requests to Standby Actors are rate-limited per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a `429` error. +The platform rate-limits incoming requests to Standby Actors per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a `429` error. ## Standby configuration -The Standby configuration consists of the following properties: +The Standby configuration has these properties: | Property | Description | | --- | --- | -| Max requests per run | The maximum number of concurrent HTTP requests a single Standby Actor run can accept. If this limit is exceeded, the system starts a new Actor run to handle the request, which may take a few seconds. | -| Desired requests per run | The number of concurrent HTTP requests a single Standby Actor run is configured to handle. If this limit is exceeded, the system preemptively starts a new Actor run to handle the additional requests. | -| Memory (MB) | The amount of memory (RAM) allocated for the Actor in Standby mode, in megabytes. With more memory, the Actor can typically handle more requests in parallel, but this also increases the number of compute units consumed and the associated cost. | -| Idle timeout (seconds) | If a Standby Actor run doesn't receive any HTTP requests within this time, the system terminates 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`). | +| Max requests per run | The maximum number of concurrent HTTP requests a single Standby Actor run can accept. When a request would exceed this limit, the platform starts a new run to handle it, which can take a few seconds. | +| Desired requests per run | The number of concurrent HTTP requests a single Standby Actor run is configured to handle. When requests exceed this number, the platform starts a new run ahead of time to handle the additional requests. | +| Memory (MB) | The amount of memory (RAM) allocated for the Actor in Standby mode, in megabytes. More memory usually lets the Actor handle more requests in parallel, but it also consumes more compute units and costs more. | +| Idle timeout (seconds) | If a run receives no HTTP requests within this time, the platform stops it. The next request might then need a new run, which can take a few seconds to start. A higher idle timeout improves responsiveness but costs more, because the run stays active longer. | +| Build | The Actor build that Standby runs use: a build tag (for example `latest`) or a build number (for example `0.1.2`). | You can see the current values in the **Endpoints** tab of the Actor detail page. If you own the Actor, you can change its default Standby configuration in the **Settings** tab. @@ -138,7 +133,7 @@ The Actor's developer can lock the Standby configuration. In that case, the task ## Billing -Standby runs are billed in the same fashion as normal runs. However, they might have unexpected costs. The Actors run in the background and consume resources even when no requests arrive, until the idle timeout terminates them. +The platform bills Standby runs like normal runs, but the costs can surprise you. A Standby run consumes resources in the background even when no requests arrive, until the idle timeout stops it. For Actors monetized with the [pay-per-event pricing model](/actors/monetize/pay-per-event), you pay the platform usage costs of the Standby runs in addition to the event charges. From caeea5de5a6ee0de0bd54b1de0db37a7876cfbf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 26 Oct 2026 20:02:48 +0100 Subject: [PATCH 3/5] Apply batched suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michal Turek Co-authored-by: Tobiáš Potoček --- sources/platform/actors/running/actor_standby.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 293c993860..4f07317466 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -12,7 +12,7 @@ To build your own Standby Actor, see [Develop Actors in Standby mode](../develop ## Check whether an Actor supports Standby mode -If an Actor has Standby mode enabled, its detail page shows the **Endpoints** tab. The tab contains the hostname of the Actor's server, and the Actor README describes the endpoints, the parameters they accept, and what they return. +If an Actor has Standby mode enabled, its detail page shows the **Server** tab. The tab contains the hostname of the Actor's server, and the Actor README describes the endpoints, the parameters they accept, and what they return. 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. You don't need to start the Actor. Send a request to that hostname and endpoint, and you get the results. @@ -52,7 +52,7 @@ Authenticate Standby requests the same way as [requests to the Apify API](../../ https://rag-web-browser.apify.actor/search?query=apify ``` -1. Append the token to the request URL as the `token` query parameter. Use this when you can't modify the request headers. +1. Append the token to the request URL as the `token` query parameter. It's less secure, so use this only when you can't modify the request headers. ```text https://rag-web-browser.apify.actor/search?query=apify&token=my_apify_token @@ -72,7 +72,7 @@ Standby mode doesn't support [restricting what an Actor can access](/integration ## Run the Actor in normal mode -You can still modify the input and select **Start** to run the Actor in normal mode. The platform always allows it, but the Actor might not support it. The run might fail or return empty results. Check the Actor README for what the Actor supports. +You can still modify the input and select **Start** to run the Actor in normal mode. The platform always allows it, but the Actor might not support it. The run might start in the Standby mode, fail, or return empty results. Check the Actor README for what the Actor supports. ## Limits and scaling @@ -100,7 +100,7 @@ Within this window, the platform first selects an Actor run to handle the reques ### Rate limits -The platform rate-limits incoming requests to Standby Actors per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a `429` error. +The platform rate-limits incoming requests to Standby Actors per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a [`429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429) error. ## Standby configuration From 89b35c2ff108e8087b36d85c94f03c468f3477fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 26 Oct 2026 20:05:42 +0100 Subject: [PATCH 4/5] docs: rename the Endpoints tab to Server --- .../actor_definition/web_server_schema/index.md | 12 ++++++------ .../programming_interface/actor_standby.md | 2 +- sources/platform/actors/running/actor_standby.md | 12 ++++++------ 3 files changed, 13 insertions(+), 13 deletions(-) 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 c78f4adfdc..341e7c3137 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 Endpoints 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 Server 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 **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. +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 **Server** 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 Endpoints tab rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) +![Apify Console showing the Server tab rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) ## Define the web server schema @@ -94,7 +94,7 @@ The build process validates `webServerSchema`, similar to other Actor schemas li The platform doesn't enforce the schema at runtime. Unlike input schema, the web server schema only documents your Actor's interface. The platform forwards incoming requests to your server without validating them or your server's responses against the schema. Your server must validate requests itself. -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. +Once deployed, the **Server** 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 @@ -106,6 +106,6 @@ Your `servers` array is replaced with the Actor's standby URL at display time. C | Field | Description | | --- | --- | -| `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. | +| `usesStandbyMode` | Must be `true` for the **Server** tab to appear. See [standby mode](/actors/development/programming-interface/standby). | +| `webServerSchema` | The OpenAPI spec that powers the **Server** tab. Defined in [`.actor/actor.json`](/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. | | `webServerMcpPath` | The HTTP path where the Actor exposes its MCP server. The Actor's MCP endpoint is the Standby URL followed by this path. See [`.actor/actor.json`](/actors/development/actor-definition/actor-json). | diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index 8e6dedcd2f..8f9578bc35 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -86,7 +86,7 @@ async def main() -> None: ## Describe your endpoints -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. Based on that definition, Apify Console 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](../../publishing/publish/actor-readme.mdx) as well, because users see the README in Apify Store before they open the Actor's detail page. +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. Based on that definition, Apify Console renders an interactive **Server** 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](../../publishing/publish/actor-readme.mdx) as well, because users see the README in Apify Store before they open the Actor's detail page. ## Run lifecycle diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 4f07317466..3a5ef94acc 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -17,7 +17,7 @@ If the Actor defines a [web server schema](../development/actor_definition/web_s You don't need to start the Actor. Send a request to that hostname and endpoint, and you get the results. -![Endpoints tab on the Actor detail page](./images/actor_standby/standby-tab.png) +![Server tab on the Actor detail page](./images/actor_standby/standby-tab.png) ## Standby URLs @@ -33,7 +33,7 @@ The Actor also responds on a URL built from its ID, which keeps working if the A https://92c4oi4fpzy7rprlf.apify.actor ``` -The Standby URL stays the same for all runs of the Actor, so you can share it publicly or hardcode it in applications that call the Actor. Copy the URL from the **Endpoints** tab instead of building it from the username and Actor name, because some Actors use a different hostname format, like `rag-web-browser.apify.actor` in the examples below. +The Standby URL stays the same for all runs of the Actor, so you can share it publicly or hardcode it in applications that call the Actor. Copy the URL from the **Server** tab instead of building it from the username and Actor name, because some Actors use a different hostname format, like `rag-web-browser.apify.actor` in the examples below. ## Send requests to the Actor @@ -72,7 +72,7 @@ Standby mode doesn't support [restricting what an Actor can access](/integration ## Run the Actor in normal mode -You can still modify the input and select **Start** to run the Actor in normal mode. The platform always allows it, but the Actor might not support it. The run might start in the Standby mode, fail, or return empty results. Check the Actor README for what the Actor supports. +You can still modify the input and select **Start** to run the Actor in normal mode. The platform always allows it, but the Actor might not support it. The run might start in the Standby mode, fail, or return empty results. Check the Actor README for what the Actor supports. ## Limits and scaling @@ -100,7 +100,7 @@ Within this window, the platform first selects an Actor run to handle the reques ### Rate limits -The platform rate-limits incoming requests to Standby Actors per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a [`429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429) error. +The platform rate-limits incoming requests to Standby Actors per user account. The limit is the same on all standard subscription plans, and custom plans can raise it. Responses include the current limit in the `X-RateLimit-Limit` header. When you exceed the limit, the platform responds with a [`429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429) error. ## Standby configuration @@ -114,14 +114,14 @@ The Standby configuration has these properties: | Idle timeout (seconds) | If a run receives no HTTP requests within this time, the platform stops it. The next request might then need a new run, which can take a few seconds to start. A higher idle timeout improves responsiveness but costs more, because the run stays active longer. | | Build | The Actor build that Standby runs use: a build tag (for example `latest`) or a build number (for example `0.1.2`). | -You can see the current values in the **Endpoints** tab of the Actor detail page. If you own the Actor, you can change its default Standby configuration in the **Settings** tab. +You can see the current values in the **Server** tab of the Actor detail page. If you own the Actor, you can change its default Standby configuration in the **Settings** tab. ### Override the configuration with a task If you use an Actor built by someone else, the Actor-level hostname always uses the developer's default configuration. To override it: 1. In [Apify Console](https://console.apify.com), create a new task from the Actor. -1. Open the **Endpoints** tab of the created task. +1. Open the **Server** tab of the created task. 1. Modify the configuration as needed. 1. In your application, use the task's hostname instead of the Actor's. From 8f58d89830db980fb1dc0307c14ddfc4686f9b8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 26 Oct 2026 20:07:39 +0100 Subject: [PATCH 5/5] docs: address review on the Standby pages Config values aren't shown on the Server tab, runs are replaced rather than migrated, and the pass-input setting was missing from the table. --- .../programming_interface/actor_standby.md | 2 +- .../platform/actors/running/actor_standby.md | 19 ++++++++++--------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index 8f9578bc35..c9b4864edb 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -156,7 +156,7 @@ async def main() -> None: ### Run termination -A run ends when its process exits, when it migrates to another machine, or when it stays idle for longer than the idle timeout. Apart from the [readiness probe](#readiness-probe), the platform doesn't check your server's health while the run is alive. A server that stays up but stops responding keeps receiving requests, so on an unrecoverable error, exit the process instead of swallowing the error. +A run ends when its process exits, when it stays idle for longer than the idle timeout, or when the platform replaces it. During a worker migration, the platform doesn't move the run to another machine. Instead, it starts a replacement run, waits until that run is ready, then stops sending requests to the old run and aborts it. Apart from the [readiness probe](#readiness-probe), the platform doesn't check your server's health while the run is alive. A server that stays up but stops responding keeps receiving requests, so on an unrecoverable error, exit the process instead of swallowing the error. ## Detect the run mode diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index 3a5ef94acc..24e59d66e6 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -62,17 +62,17 @@ The platform removes the token from the request before forwarding it, so the tok If you're developing a Standby Actor, use the token from the `APIFY_TOKEN` [environment variable](../development/programming_interface/environment_variables.md#system-environment-variables) to call the Apify API, as in any other Actor. -To let third-party services call your Actor without access to your entire account, send Standby requests with [scoped tokens](/integrations/api#limited-permissions). +Scoped tokens work for Standby requests. To let a third-party service call your Actor without access to your entire account, give it a [scoped token](/integrations/api#limited-permissions) with only the permissions it needs. :::caution Restricted access is not supported -Standby mode doesn't support [restricting what an Actor can access](/integrations/api#restricted-access-restrict-what-actors-can-access-using-the-scope-of-this-actor) with a scoped token. +A scoped token also has a [restricted access](/integrations/api#restricted-access-restrict-what-actors-can-access-using-the-scope-of-this-actor) option that limits what the Actor's run can access. Standby mode doesn't support that option. ::: ## Run the Actor in normal mode -You can still modify the input and select **Start** to run the Actor in normal mode. The platform always allows it, but the Actor might not support it. The run might start in the Standby mode, fail, or return empty results. Check the Actor README for what the Actor supports. +If the Actor has no input schema, Apify Console disables the **Input** tab. Otherwise, you can modify the input and select **Start** to run the Actor in normal mode. The Actor might not support normal mode. The run might then start in Standby mode, fail, or return empty results. Check the Actor README for what the Actor supports. ## Limits and scaling @@ -113,30 +113,31 @@ The Standby configuration has these properties: | Memory (MB) | The amount of memory (RAM) allocated for the Actor in Standby mode, in megabytes. More memory usually lets the Actor handle more requests in parallel, but it also consumes more compute units and costs more. | | Idle timeout (seconds) | If a run receives no HTTP requests within this time, the platform stops it. The next request might then need a new run, which can take a few seconds to start. A higher idle timeout improves responsiveness but costs more, because the run stays active longer. | | Build | The Actor build that Standby runs use: a build tag (for example `latest`) or a build number (for example `0.1.2`). | +| Validate and pass Actor input | If enabled, the platform validates the Actor input and passes it to the run even when the run starts in Standby mode. Use it to start Standby runs with different configurations. If disabled, the input applies only to manual runs and testing, independent of Standby mode. | -You can see the current values in the **Server** tab of the Actor detail page. If you own the Actor, you can change its default Standby configuration in the **Settings** tab. +If you own the Actor, you can see and change its default Standby configuration in the **Settings** tab. ### Override the configuration with a task If you use an Actor built by someone else, the Actor-level hostname always uses the developer's default configuration. To override it: -1. In [Apify Console](https://console.apify.com), create a new task from the Actor. -1. Open the **Server** tab of the created task. +1. In [Apify Console](https://console.apify.com), open the Actor and select **Save as a new task**. +1. Open the task's **Settings** tab. 1. Modify the configuration as needed. 1. In your application, use the task's hostname instead of the Actor's. :::note Developers can lock the configuration -The Actor's developer can lock the Standby configuration. In that case, the task-level settings have no effect. +If the developer locked the Standby configuration, the task-level settings have no effect. ::: ## Billing -The platform bills Standby runs like normal runs, but the costs can surprise you. A Standby run consumes resources in the background even when no requests arrive, until the idle timeout stops it. +The platform bills Standby runs like normal runs. A Standby run also consumes resources while it waits for requests, until the idle timeout stops it. Expect usage even when no requests arrive. For Actors monetized with the [pay-per-event pricing model](/actors/monetize/pay-per-event), you pay the platform usage costs of the Standby runs in addition to the event charges. ## Use Standby Actors as MCP servers -If the Actor exposes a [Model Context Protocol (MCP)](../../agents/mcp.md) server, its MCP endpoint is the Standby URL followed by the path defined in the Actor's [`webServerMcpPath`](../development/actor_definition/actor_json.md) property. Authenticate requests to the MCP endpoint the same way as any other Standby request. +If the Actor exposes a [Model Context Protocol (MCP)](../../agents/mcp.md) server, its MCP endpoint is the Standby URL followed by the path defined in the Actor's [`webServerMcpPath`](../development/actor_definition/actor_json.md) property. Apify Console shows the MCP URL in the Actor's **Server** tab. Authenticate requests to the MCP endpoint the same way as any other Standby request.