Skip to main content
Version: 3.5

Server Actors

A Server Actor (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. To send a request, use ActorServerClient.request. It takes the path on the Actor's server, and optionally the HTTP method, query parameters, headers, and a body:

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)

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, its README, or its OpenAPI specification. For details, see Server URL and OpenAPI specification.

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

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

  • ActorServerClient.get_url returns the server's URL. It fetches and reuses the URL the same way as request.
  • ActorServerClient.get_openapi_spec returns the server's OpenAPI specification as a dict. It's the 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:

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']))

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 in the platform documentation.

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.

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()

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.

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.

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.