# Server Actors

Copy for LLM

A [Server Actor](https://docs.apify.com/platform/actors/running/standby) (formerly Actor Standby) runs a web server. You call it over HTTP, and the platform keeps a run ready to answer, so each call skips the run startup.

Formerly Actor Standby

Actor Standby is the former name of Server Actors, and it'll be deprecated. The platform documentation and the API still use it, for example in the Actor's `standby_url` and `actor_standby` fields. In the client, `ActorClient.standby` is a deprecated alias of `ActorClient.server`, and the `actor_standby_*` arguments of the Actor and task `update` and `create` methods are deprecated aliases of their `server_*` counterparts, such as `server_build` for `actor_standby_build`. The aliases will be removed in v4.

To work with a Server Actor, get its server client with [`ActorClient.server`](https://docs.apify.com/api/client/python/reference/class/ActorClient.md#server). To send a request, use [`ActorServerClient.request`](https://docs.apify.com/api/client/python/reference/class/ActorServerClient.md#request). It takes the path on the Actor's server, and optionally the HTTP method, query parameters, headers, and a body:

* Async client
* Sync client

```
from http import HTTPStatus



from apify_client import ApifyClientAsync



TOKEN = 'MY-APIFY-TOKEN'





async def main() -> None:

    apify_client = ApifyClientAsync(TOKEN)

    actor_server_client = apify_client.actor('username/actor-name').server()



    # Send a GET request to the /search endpoint of the Actor's server. The method

    # returns error responses too, so check the status first.

    response = await actor_server_client.request('/search', params={'q': 'apify'})

    if response.status_code != HTTPStatus.OK:

        raise RuntimeError(f'Search failed with status {response.status_code}')

    print(response.json())



    # Send a POST request with a JSON body.

    response = await actor_server_client.request(

        '/items',

        method='POST',

        json={'url': 'https://apify.com'},

    )

    print(response.status_code)
```

```
from http import HTTPStatus



from apify_client import ApifyClient



TOKEN = 'MY-APIFY-TOKEN'





def main() -> None:

    apify_client = ApifyClient(TOKEN)

    actor_server_client = apify_client.actor('username/actor-name').server()



    # Send a GET request to the /search endpoint of the Actor's server. The method

    # returns error responses too, so check the status first.

    response = actor_server_client.request('/search', params={'q': 'apify'})

    if response.status_code != HTTPStatus.OK:

        raise RuntimeError(f'Search failed with status {response.status_code}')

    print(response.json())



    # Send a POST request with a JSON body.

    response = actor_server_client.request(

        '/items',

        method='POST',

        json={'url': 'https://apify.com'},

    )

    print(response.status_code)
```

The method returns the server's response. To read a large body in chunks, pass `stream=True` and close the response when you're done with it. To find out which endpoints an Actor serves, see its page in [Apify Store](https://apify.com/store), its README, or its OpenAPI specification. For details, see [Server URL and OpenAPI specification](#server-url-and-openapi-specification).

## How the request is sent[](#how-the-request-is-sent)

Note that:

* The client takes the server's URL from the Actor's `standby_url`. It fetches the Actor from the API on the first call and reuses the URL for later calls through the same `ActorClient`. If the Actor isn't a Server Actor, the server client raises an `ApifyClientError`.
* The path is always resolved against that URL, so a path can't send the request to another host.
* By default, the request body is sent uncompressed, since the Actor's server may not decode a compressed body. If the server decodes it, pass `compression`, for example `compression='gzip'`. The client then compresses large bodies the same way as for API calls.

## Server URL and OpenAPI specification[](#server-url-and-openapi-specification)

The Actor server client also gives you the server's URL and its OpenAPI specification:

* [`ActorServerClient.get_url`](https://docs.apify.com/api/client/python/reference/class/ActorServerClient.md#get_url) returns the server's URL. It fetches and reuses the URL the same way as `request`.
* [`ActorServerClient.get_openapi_spec`](https://docs.apify.com/api/client/python/reference/class/ActorServerClient.md#get_openapi_spec) returns the server's OpenAPI specification as a `dict`. It's the [web server schema](https://docs.apify.com/platform/actors/development/actor-definition/web-server-schema) from the Actor's definition, taken from the build that serves the server interface. That's the build set in the Actor's `actor_standby.build` field, or `latest` if none is set. If the Actor doesn't define a web server schema, the method returns `None`.

The following example prints the server's URL and the paths of its endpoints:

* Async client
* Sync client

```
from apify_client import ApifyClientAsync



TOKEN = 'MY-APIFY-TOKEN'





async def main() -> None:

    apify_client = ApifyClientAsync(TOKEN)

    actor_server_client = apify_client.actor('username/actor-name').server()



    # Get the URL of the Actor's server.

    server_url = await actor_server_client.get_url()

    print(server_url)



    # Get the OpenAPI specification and list the server's endpoints.

    spec = await actor_server_client.get_openapi_spec()

    if spec is not None:

        print(list(spec['paths']))
```

```
from apify_client import ApifyClient



TOKEN = 'MY-APIFY-TOKEN'





def main() -> None:

    apify_client = ApifyClient(TOKEN)

    actor_server_client = apify_client.actor('username/actor-name').server()



    # Get the URL of the Actor's server.

    server_url = actor_server_client.get_url()

    print(server_url)



    # Get the OpenAPI specification and list the server's endpoints.

    spec = actor_server_client.get_openapi_spec()

    if spec is not None:

        print(list(spec['paths']))
```

## Authentication[](#authentication)

The request carries the client's API token in the `X-Apify-Authorization` header. The platform removes the token before it forwards the request, so the token doesn't reach the Actor's code. The method doesn't follow redirects and returns a redirect response as it is, since following it would send the token to a host the Actor's code picked.

The headers you pass in `headers` reach the Actor's server as they are. If the Actor reads the `Authorization` header for its own authentication, pass that header in `headers`.

For details, see [How do I authenticate my requests](https://docs.apify.com/platform/actors/running/standby#how-do-i-authenticate-my-requests) in the platform documentation.

## Calling a Server Actor from a Server Actor[](#calling-a-server-actor-from-a-server-actor)

A multi-tenant Server Actor shares the developer's runs among its users, so the platform tells requests apart by an ID it sends in the `X-Actor-Request-ID` header of each request it forwards to the Actor. The Actor uses that ID to charge the request's caller, and to pass the caller's pricing tier on to Actors it calls.

When your multi-tenant Server Actor calls another one while handling a request, pass the `X-Actor-Request-ID` header of the incoming request in `parent_request_id`. The client sends it as the same header on the outgoing request, so the called Actor charges at the pricing tier of the incoming one. Use a client created with the run's `APIFY_TOKEN`. For details, see [Compose multi-tenant Server Actors](https://docs.apify.com/platform/actors/development/programming-interface/standby#compose-server-actors).

* Async client
* Sync client

```
import os

from collections.abc import Mapping

from typing import Any



from apify_client import ApifyClientAsync





async def search_other_actor(incoming_headers: Mapping[str, str]) -> Any:

    # Call this while handling a request your Server Actor received, with the headers

    # object of that incoming request (case-insensitive, as web frameworks provide it).

    # The client uses the token of the Actor's run.

    apify_client = ApifyClientAsync(os.environ['APIFY_TOKEN'])

    other_server_client = apify_client.actor('username/other-actor').server()



    # The outgoing request is charged at the pricing tier of the incoming one.

    response = await other_server_client.request(

        '/search',

        params={'q': 'apify'},

        parent_request_id=incoming_headers['X-Actor-Request-ID'],

    )

    return response.json()
```

```
import os

from collections.abc import Mapping

from typing import Any



from apify_client import ApifyClient





def search_other_actor(incoming_headers: Mapping[str, str]) -> Any:

    # Call this while handling a request your Server Actor received, with the headers

    # object of that incoming request (case-insensitive, as web frameworks provide it).

    # The client uses the token of the Actor's run.

    apify_client = ApifyClient(os.environ['APIFY_TOKEN'])

    other_server_client = apify_client.actor('username/other-actor').server()



    # The outgoing request is charged at the pricing tier of the incoming one.

    response = other_server_client.request(

        '/search',

        params={'q': 'apify'},

        parent_request_id=incoming_headers['X-Actor-Request-ID'],

    )

    return response.json()
```

## Timeouts, retries, and errors[](#timeouts-retries-and-errors)

When no server run is ready, the first request waits for the platform to start one. The method uses the `long` timeout tier by default for that reason. You can pass a different `timeout`, the same way as for API calls. For details, see [Timeouts](https://docs.apify.com/api/client/python/docs/concepts/timeouts.md).

The method returns the server's response whatever its status, so check `status_code` before you use the body. Only rate-limit (429) and Service Unavailable (503) responses are retried, with the client's retry settings. Once the retries run out, the method returns the last response. The platform sends these when it can't pass the request to a server run, but the Actor's code can return them too, and then a retry sends the request to the Actor again. Network errors and timeouts aren't retried, since the Actor may have already handled the request. For details, see [Retries](https://docs.apify.com/api/client/python/docs/concepts/retries.md).

The method raises only when it doesn't get a response from the server: an `ApifyApiError` when the API can't return the Actor, for example because it doesn't exist, an `ApifyClientError` when it isn't a Server Actor, or the HTTP library's error when the request fails or times out. For details, see [Error handling](https://docs.apify.com/api/client/python/docs/concepts/error-handling.md).
