Skip to main content
Version: Next

Actor <Data>

Actor class serves as an alternative approach to the static helpers exported from the package. It allows to pass configuration that will be used on the instance methods. Environment variables will have precedence over this configuration. See Configuration for details about what can be configured and what are the default values.

Index

Constructors

constructor

  • new Actor<Data>(options?: ConfigurationOptions): Actor<Data>
  • Type parameters

    • Data: Dictionary = Dictionary

    Parameters

    • options: ConfigurationOptions = {}

    Returns Actor<Data>

Properties

initialized

initialized: boolean = false

Whether the actor instance was initialized. This is set by calling Actor.init.

Accessors

staticapifyClient

staticconfig

Methods

getInputOrThrow

  • getInputOrThrow<T>(): Promise<T>
  • Gets the actor input value just like the Actor.getInput method, but throws if it is not found.


    Type parameters

    • T = string | Dictionary | Buffer

    Returns Promise<T>

useState

  • useState<State>(name?: string, defaultValue?: State, options?: UseStateOptions): Promise<State>
  • Easily create and manage state values. All state values are automatically persisted.

    Values can be modified by simply using the assignment operator.


    Type parameters

    • State: Dictionary = Dictionary

    Parameters

    • optionalname: string

      The name of the store to use.

    • defaultValue: State = ...

      If the store does not yet have a value in it, the value will be initialized with the defaultValue you provide.

    • optionaloptions: UseStateOptions

      An optional object parameter where a custom keyValueStoreName and config can be passed in.

    Returns Promise<State>

staticabort

  • Aborts given actor run on the Apify platform using the current user account (determined by the APIFY_TOKEN environment variable).

    The result of the function is an ActorRun object that contains details about the actor run.

    For more information about actors, read the documentation.

    Example usage:

    const run = await Actor.abort(runId);

    Parameters

    Returns Promise<ActorRun>

staticaddWebhook

  • Creates an ad-hoc webhook for the current actor run, which lets you receive a notification when the actor run finished or failed. For more information about Apify actor webhooks, please see the documentation.

    Note that webhooks are only supported for actors running on the Apify platform. In local environment, the function will print a warning and have no effect.


    Parameters

    Returns Promise<undefined | Webhook>

    The return value is the Webhook object. For more information, see the Get webhook API endpoint.

staticcall

  • Runs an actor on the Apify platform using the current user account (determined by the APIFY_TOKEN environment variable).

    The result of the function is an ActorRun object that contains details about the actor run.

    If you want to run an actor task rather than an actor, please use the Actor.callTask function instead.

    For more information about actors, read the documentation.

    Example usage:

    const run = await Actor.call('apify/hello-world', { myInput: 123 });

    Parameters

    • actorId: string

      Allowed formats are username/actor-name, userId/actor-name or actor ID.

    • optionalinput: unknown

      Input for the actor. If it is an object, it will be stringified to JSON and its content type set to application/json; charset=utf-8. Otherwise the options.contentType parameter must be provided.

    • optionaloptions: CallOptions = {}

    Returns Promise<ActorRun>

staticcallTask

  • Runs an actor task on the Apify platform using the current user account (determined by the APIFY_TOKEN environment variable).

    The result of the function is an ActorRun object that contains details about the actor run.

    Note that an actor task is a saved input configuration and options for an actor. If you want to run an actor directly rather than an actor task, please use the Actor.call function instead.

    For more information about actor tasks, read the documentation.

    Example usage:

    const run = await Actor.callTask('bob/some-task');

    Parameters

    • taskId: string

      Allowed formats are username/task-name, userId/task-name or task ID.

    • optionalinput: Dictionary

      Input overrides for the actor task. If it is an object, it will be stringified to JSON and its content type set to application/json; charset=utf-8. Provided input will be merged with actor task input.

    • optionaloptions: CallTaskOptions = {}

    Returns Promise<ActorRun>

staticcreateProxyConfiguration

  • Creates a proxy configuration and returns a promise resolving to an instance of the ProxyConfiguration class that is already initialized.

    Configures connection to a proxy server with the provided options. Proxy servers are used to prevent target websites from blocking your crawlers based on IP address rate limits or blacklists. Setting proxy configuration in your crawlers automatically configures them to use the selected proxies for all connections.

    For more details and code examples, see the ProxyConfiguration class.


    // Returns initialized proxy configuration class
    const proxyConfiguration = await Actor.createProxyConfiguration({
    groups: ['GROUP1', 'GROUP2'] // List of Apify proxy groups
    countryCode: 'US'
    });

    const crawler = new CheerioCrawler({
    // ...
    proxyConfiguration,
    requestHandler({ proxyInfo }) {
    const usedProxyUrl = proxyInfo.url; // Getting the proxy URL
    }
    })

    For compatibility with existing Actor Input UI (Input Schema), this function returns undefined when the following object is passed as proxyConfigurationOptions.

    { useApifyProxy: false }

    Parameters

    Returns Promise<undefined | ProxyConfiguration>

staticexit

  • Gracefully exits the actor run with the provided status message and exit code.


    Parameters

    • optionalmessageOrOptions: string | ExitOptions

      First parameter accepts either a string (a terminal status message) or an ExitOptions object.

    • options: ExitOptions = {}

      Second parameter accepts an ExitOptions object.

    Returns Promise<void>

staticfail

  • Calls Actor.exit() with options.exitCode set to 1.


    Parameters

    • optionalmessageOrOptions: string | ExitOptions

      First parameter accepts either a string (a terminal status message) or an ExitOptions object.

    • options: ExitOptions = {}

      Second parameter accepts an ExitOptions object.

    Returns Promise<void>

staticgetEnv

  • Returns a new ApifyEnv object which contains information parsed from all the Apify environment variables.

    For the list of the Apify environment variables, see Actor documentation. If some of the variables are not defined or are invalid, the corresponding value in the resulting object will be null.


    Returns ApifyEnv

staticgetInput

  • getInput<T>(): Promise<null | T>
  • Gets the actor input value from the default KeyValueStore associated with the current actor run.

    This is just a convenient shortcut for keyValueStore.getValue('INPUT'). For example, calling the following code:

    const input = await Actor.getInput();

    is equivalent to:

    const store = await Actor.openKeyValueStore();
    await store.getValue('INPUT');

    Note that the getInput() function does not cache the value read from the key-value store. If you need to use the input multiple times in your actor, it is far more efficient to read it once and store it locally.

    For more information, see Actor.openKeyValueStore and KeyValueStore.getValue.


    Type parameters

    • T = string | Dictionary | Buffer

    Returns Promise<null | T>

    Returns a promise that resolves to an object, string or Buffer, depending on the MIME content type of the record, or null if the record is missing.

staticgetInputOrThrow

  • getInputOrThrow<T>(): Promise<T>
  • Gets the actor input value just like the Actor.getInput method, but throws if it is not found.


    Type parameters

    • T = string | Dictionary | Buffer

    Returns Promise<T>

staticgetValue

  • getValue<T>(key: string): Promise<null | T>
  • Gets a value from the default KeyValueStore associated with the current actor run.

    This is just a convenient shortcut for KeyValueStore.getValue. For example, calling the following code:

    const value = await Actor.getValue('my-key');

    is equivalent to:

    const store = await Actor.openKeyValueStore();
    const value = await store.getValue('my-key');

    To store the value to the default key-value store, you can use the Actor.setValue function.

    For more information, see Actor.openKeyValueStore and KeyValueStore.getValue.


    Type parameters

    • T = unknown

    Parameters

    • key: string

      Unique record key.

    Returns Promise<null | T>

    Returns a promise that resolves to an object, string or Buffer, depending on the MIME content type of the record, or null if the record is missing.

staticinit

  • Parameters

    Returns Promise<void>

staticisAtHome

  • isAtHome(): boolean
  • Returns true when code is running on Apify platform and false otherwise (for example locally).


    Returns boolean

staticmain

  • Runs the main user function that performs the job of the actor and terminates the process when the user function finishes.

    The Actor.main() function is optional and is provided merely for your convenience. It is mainly useful when you’re running your code as an actor on the Apify platform. However, if you want to use Apify SDK tools directly inside your existing projects, e.g. running in an Express server, on Google Cloud functions or AWS Lambda, it’s better to avoid it since the function terminates the main process when it finishes!

    The Actor.main() function performs the following actions:

    • When running on the Apify platform (i.e. APIFY_IS_AT_HOME environment variable is set), it sets up a connection to listen for platform events. For example, to get a notification about an imminent migration to another server. See Actor.events for details.
    • It checks that either APIFY_TOKEN or APIFY_LOCAL_STORAGE_DIR environment variable is defined. If not, the functions sets APIFY_LOCAL_STORAGE_DIR to ./apify_storage inside the current working directory. This is to simplify running code examples.
    • It invokes the user function passed as the userFunc parameter.
    • If the user function returned a promise, waits for it to resolve.
    • If the user function throws an exception or some other error is encountered, prints error details to console so that they are stored to the log.
    • Exits the Node.js process, with zero exit code on success and non-zero on errors.

    The user function can be synchronous:

    await Actor.main(() => {
    // My synchronous function that returns immediately
    console.log('Hello world from actor!');
    });

    If the user function returns a promise, it is considered asynchronous:

    import { gotScraping } from 'got-scraping';

    await Actor.main(() => {
    // My asynchronous function that returns a promise
    return gotScraping('http://www.example.com').then((html) => {
    console.log(html);
    });
    });

    To simplify your code, you can take advantage of the async/await keywords:

    import { gotScraping } from 'got-scraping';

    await Actor.main(async () => {
    // My asynchronous function
    const html = await gotScraping('http://www.example.com');
    console.log(html);
    });

    Type parameters

    • T

    Parameters

    • userFunc: UserFunc<T>

      User function to be executed. If it returns a promise, the promise will be awaited. The user function is called with no arguments.

    • optionaloptions: MainOptions

    Returns Promise<T>

staticmetamorph

  • metamorph(targetActorId: string, input?: unknown, options?: MetamorphOptions): Promise<void>
  • Transforms this actor run to an actor run of a given actor. The system stops the current container and starts the new container instead. All the default storages are preserved and the new input is stored under the INPUT-METAMORPH-1 key in the same default key-value store.


    Parameters

    • targetActorId: string

      Either username/actor-name or actor ID of an actor to which we want to metamorph.

    • optionalinput: unknown

      Input for the actor. If it is an object, it will be stringified to JSON and its content type set to application/json; charset=utf-8. Otherwise, the options.contentType parameter must be provided.

    • optionaloptions: MetamorphOptions = {}

    Returns Promise<void>

staticnewClient

  • Returns a new instance of the Apify API client. The ApifyClient class is provided by the apify-client NPM package, and it is automatically configured using the APIFY_API_BASE_URL, and APIFY_TOKEN environment variables. You can override the token via the available options. That’s useful if you want to use the client as a different Apify user than the SDK internals are using.


    Parameters

    Returns ApifyClient

staticoff

  • off(event: EventTypeName, listener?: (...args: any[]) => any): void
  • Parameters

    • event: EventTypeName
    • optionallistener: (...args: any[]) => any

    Returns void

staticon

  • on(event: EventTypeName, listener: (...args: any[]) => any): void
  • Parameters

    • event: EventTypeName
    • listener: (...args: any[]) => any

    Returns void

staticopenDataset

  • Opens a dataset and returns a promise resolving to an instance of the Dataset class.

    Datasets are used to store structured data where each object stored has the same attributes, such as online store products or real estate offers. The actual data is stored either on the local filesystem or in the cloud.

    For more details and code examples, see the Dataset class.


    Type parameters

    • Data: Dictionary = Dictionary

    Parameters

    • optionaldatasetIdOrName: null | string

      ID or name of the dataset to be opened. If null or undefined, the function returns the default dataset associated with the actor run.

    • optionaloptions: OpenStorageOptions = {}

    Returns Promise<Dataset<Data>>

staticopenKeyValueStore

  • Opens a key-value store and returns a promise resolving to an instance of the KeyValueStore class.

    Key-value stores are used to store records or files, along with their MIME content type. The records are stored and retrieved using a unique key. The actual data is stored either on a local filesystem or in the Apify cloud.

    For more details and code examples, see the KeyValueStore class.


    Parameters

    • optionalstoreIdOrName: null | string

      ID or name of the key-value store to be opened. If null or undefined, the function returns the default key-value store associated with the actor run.

    • optionaloptions: OpenStorageOptions = {}

    Returns Promise<KeyValueStore>

staticopenRequestQueue

  • Opens a request queue and returns a promise resolving to an instance of the RequestQueue class.

    RequestQueue represents a queue of URLs to crawl, which is stored either on local filesystem or in the cloud. The queue is used for deep crawling of websites, where you start with several URLs and then recursively follow links to other pages. The data structure supports both breadth-first and depth-first crawling orders.

    For more details and code examples, see the RequestQueue class.


    Parameters

    • optionalqueueIdOrName: null | string

      ID or name of the request queue to be opened. If null or undefined, the function returns the default request queue associated with the actor run.

    • optionaloptions: OpenStorageOptions = {}

    Returns Promise<RequestQueue>

staticpushData

  • pushData<Data>(item: Data | Data[]): Promise<void>
  • Stores an object or an array of objects to the default Dataset of the current actor run.

    This is just a convenient shortcut for Dataset.pushData. For example, calling the following code:

    await Actor.pushData({ myValue: 123 });

    is equivalent to:

    const dataset = await Actor.openDataset();
    await dataset.pushData({ myValue: 123 });

    For more information, see Actor.openDataset and Dataset.pushData

    IMPORTANT: Make sure to use the await keyword when calling pushData(), otherwise the actor process might finish before the data are stored!


    Type parameters

    • Data: Dictionary = Dictionary

    Parameters

    • item: Data | Data[]

      Object or array of objects containing data to be stored in the default dataset. The objects must be serializable to JSON and the JSON representation of each object must be smaller than 9MB.

    Returns Promise<void>

staticreboot

  • Internally reboots this actor run. The system stops the current container and starts a new container with the same run id. This can be used to get the Actor out of irrecoverable error state and continue where it left off.


    Parameters

    Returns Promise<void>

staticsetStatusMessage

  • setStatusMessage(statusMessage: string, options?: SetStatusMessageOptions): Promise<ActorRun>
  • Sets the status message for the current actor run.


    Parameters

    • statusMessage: string

      The status message to set.

    • optionaloptions: SetStatusMessageOptions

    Returns Promise<ActorRun>

    The return value is the Run object. When run locally, this method returns empty object ({}). For more information, see the Actor Runs API endpoints.

staticsetValue

  • setValue<T>(key: string, value: null | T, options?: RecordOptions): Promise<void>
  • Stores or deletes a value in the default KeyValueStore associated with the current actor run.

    This is just a convenient shortcut for KeyValueStore.setValue. For example, calling the following code:

    await Actor.setValue('OUTPUT', { foo: "bar" });

    is equivalent to:

    const store = await Actor.openKeyValueStore();
    await store.setValue('OUTPUT', { foo: "bar" });

    To get a value from the default key-value store, you can use the Actor.getValue function.

    For more information, see Actor.openKeyValueStore and KeyValueStore.getValue.


    Type parameters

    • T

    Parameters

    • key: string

      Unique record key.

    • value: null | T

      Record data, which can be one of the following values:

      • If null, the record in the key-value store is deleted.
      • If no options.contentType is specified, value can be any JavaScript object, and it will be stringified to JSON.
      • If options.contentType is set, value is taken as is, and it must be a String or Buffer. For any other value an error will be thrown.
    • optionaloptions: RecordOptions = {}

    Returns Promise<void>

staticstart

  • Runs an actor on the Apify platform using the current user account (determined by the APIFY_TOKEN environment variable), unlike Actor.call, this method just starts the run without waiting for finish.

    The result of the function is an ActorRun object that contains details about the actor run.

    For more information about actors, read the documentation.

    Example usage:

    const run = await Actor.start('apify/hello-world', { myInput: 123 });

    Parameters

    • actorId: string

      Allowed formats are username/actor-name, userId/actor-name or actor ID.

    • optionalinput: Dictionary

      Input for the actor. If it is an object, it will be stringified to JSON and its content type set to application/json; charset=utf-8. Otherwise the options.contentType parameter must be provided.

    • optionaloptions: CallOptions = {}

    Returns Promise<ActorRun>

staticuseState

  • useState<State>(name?: string, defaultValue?: State, options?: UseStateOptions): Promise<State>
  • Easily create and manage state values. All state values are automatically persisted.

    Values can be modified by simply using the assignment operator.


    Type parameters

    • State: Dictionary = Dictionary

    Parameters

    • optionalname: string

      The name of the store to use.

    • defaultValue: State = ...

      If the store does not yet have a value in it, the value will be initialized with the defaultValue you provide.

    • optionaloptions: UseStateOptions

      An optional object parameter where a custom keyValueStoreName and config can be passed in.

    Returns Promise<State>