Skip to main content
Version: Next

Server Actors

Copy for LLM

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 standbyUrl and actorStandby fields. In the client, ActorClient.standby() is a deprecated alias of ActorClient.server() that 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:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
const actorServerClient = 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.
const searchResponse = await actorServerClient.request('/search', { params: { q: 'apify' } });
if (searchResponse.status !== 200) throw new Error(`Search failed with status ${searchResponse.status}`);
console.log(searchResponse.data);

// Send a POST request with a JSON body.
const itemsResponse = await actorServerClient.request('/items', {
    method: 'POST',
    data: { url: 'https://apify.com' },
});
console.log(itemsResponse.status);

The method resolves to the server's response, with the body parsed by its content type in data. To get the body as raw bytes, pass responseType: 'buffer'. In Node.js, pass responseType: 'stream' to get it as a Readable stream. 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 standbyUrl. 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 throws 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.getUrl() returns the server's URL. It fetches and reuses the URL the same way as request().
  • ActorServerClient.getOpenApiSpec() returns the server's OpenAPI specification as an object. 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 actorStandby.build field, or latest if none is set. If the Actor doesn't define a web server schema, the method returns undefined.

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

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
const actorServerClient = client.actor('username/actor-name').server();

// Get the URL of the Actor's server.
const serverUrl = await actorServerClient.getUrl();
console.log(serverUrl);

// Get the OpenAPI specification and list the server's endpoints.
const spec = await actorServerClient.getOpenApiSpec();
if (spec) {
    console.log(Object.keys(spec.paths as Record<string, unknown>));
}

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. In a browser, the browser follows redirects itself, so there the token goes with a redirect.

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.

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 timeoutSecs, or a signal to abort the request, the same way as for API calls. For details, see Timeouts.

The method returns the server's response whatever its status, so check status before you use data. 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 throws 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 transport error when the request fails or times out. For details, see Error handling.

With the default responseType: 'parsed', a body that doesn't parse as its Content-Type says is handled by status. A success response throws an InvalidResponseBodyError. An error response is returned with the raw bytes in data, so you still get its status. If the server may send such bodies, pass responseType: 'buffer' and parse the body yourself.