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.
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:
- 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, 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 sameActorClient. If the Actor isn't a Server Actor, the server client raises anApifyClientError. - 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 examplecompression='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_urlreturns the server's URL. It fetches and reuses the URL the same way asrequest.ActorServerClient.get_openapi_specreturns the server's OpenAPI specification as adict. 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'sactor_standby.buildfield, orlatestif none is set. If the Actor doesn't define a web server schema, the method returnsNone.
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
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.
- 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
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.