Actor <Data>
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
Parameters
options: ActorOptions = {}
Returns Actor<Data>
Properties
initialized
Whether the Actor instance was initialized. This is set by calling Actor.init.
Accessors
childRuns
Clients for the child runs started with the
runNameoption, keyed by that name, including the runs started before a migration or resurrection of this run. Each client points to the current run under its name.await Actor.childRuns['my-child'].waitForFinish();A run started with a custom
tokenuses that token, except for a run started before a migration or resurrection, which uses the default client. The tracked runs, including the earlier runs replaced under the same name, are stored in the default key-value store under the__ACTOR_CHILD_RUNSkey.Returns Record<string, RunClient>
staticapifyClient
Default ApifyClient instance.
Returns ApifyClient
staticchildRuns
Clients for the child runs started with the
runNameoption, keyed by that name, including the runs started before a migration or resurrection of this run. Each client points to the current run under its name.await Actor.childRuns['my-child'].waitForFinish();A run started with a custom
tokenuses that token, except for a run started before a migration or resurrection, which uses the default client. The tracked runs, including the earlier runs replaced under the same name, are stored in the default key-value store under the__ACTOR_CHILD_RUNSkey.Returns Record<string, RunClient>
staticconfiguration
Default Configuration instance.
Returns Configuration
Methods
useState
Easily create and manage state values. All state values are automatically persisted.
Values can be modified by simply using the assignment operator.
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
defaultValueyou provide.optionaloptions: UseStateOptions
An optional object parameter where a custom
keyValueStoreNameandconfigcan be passed in.
Returns Promise<State>
staticabort
Aborts given Actor run on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment 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
runId: string
options: AbortOptions = {}
Returns Promise<Run>
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
options: WebhookOptions
Returns Promise<undefined | WebhookResource>
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_TOKENenvironment 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-nameor Actor ID.optionalinput: ActorInput
Input for the Actor. A plain object is stringified to JSON with content type
application/json; charset=utf-8. ABufferis sent as-is and needsoptions.contentType.optionaloptions: CallOptions = {}
Returns Promise<Run>
staticcallTask
Runs an Actor task on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment 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-nameor 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<Run>
staticcharge
Charge for a specified number of events - sub-operations of the Actor.
This method attempts to charge for the specified number of events, but may charge fewer if doing so would exceed the total budget limit (
maxTotalChargeUsd).Important: When using the
countparameter to charge for multiple events at once, be aware that the charge may be partially fulfilled — i.e.chargedCountcan be less than the requestedcount. Always check the returnedchargedCountto know how many events were actually charged, and only perform that much work. If your work is meaningfully divisible into individual units, prefer callingcharge()once per unit rather than batching viacount— this gives finer control over budget consumption and avoids situations where more work is requested than the budget allows.Parameters
options: ChargeOptions
The name of the event to charge for and the number of events to be charged.
Returns Promise<ChargeResult>
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 classconst proxyConfiguration = await Actor.createProxyConfiguration({groups: ['GROUP1', 'GROUP2'] // List of Apify proxy groupscountryCode: '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
undefinedwhen the following object is passed asproxyConfigurationOptions.{ useApifyProxy: false }As part of the init process, we verify the configuration by checking the proxy status endpoint. This can make the init slower, to opt-out of this, use
checkAccess: false(defaults totrue).Parameters
proxyConfigurationOptions: ProxyConfigurationOptions & { useApifyProxy?: boolean } = {}
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
ExitOptionsobject.options: ExitOptions = {}
Second parameter accepts an
ExitOptionsobject.
Returns Promise<void>
staticfail
Calls
Actor.exit()withoptions.exitCodeset to1.Parameters
optionalmessageOrOptions: string | ExitOptions
First parameter accepts either a string (a terminal status message) or an
ExitOptionsobject.options: ExitOptions = {}
Second parameter accepts an
ExitOptionsobject.
Returns Promise<void>
staticgetChargingManager
Retrieve the charging manager to access granular pricing information.
Returns ChargingManager
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
Gets the Actor input value from the default KeyValueStore associated with the current Actor run.
The input is the record stored under the configured input key (
ACTOR_INPUT_KEY, defaultINPUT):const input = await Actor.getInput();A record stored as
application/octet-stream— which is what a local input file without an extension is read as — is parsed with JSON5 when it parses, and returned as aBufferotherwise.When running locally and the store holds no such record, the input is read from a
<inputKey>or<inputKey>.jsonfile in the current working directory instead.Throws an ActorInputError when no input is found (
code: 'NOT_FOUND'), when both input files exist in the working directory ('MULTIPLE_FILES'), when a JSON input does not parse ('PARSE_FAILED') or when its secret fields cannot be decrypted ('DECRYPTION_FAILED'). If your Actor can run without input, catch the'NOT_FOUND'case and rethrow the rest:let input = {};try {input = await Actor.getInput();} catch (error) {if (!(error instanceof ActorInputError) || error.code !== 'NOT_FOUND') throw error;}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.
Returns Promise<T>
Returns a promise that resolves to an object, string or
Buffer, depending on the MIME content type of the record.Throws - When the input cannot be produced; see
code.
staticgetValue
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.
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, ornullif the record is missing.
staticinit
Initializes the Actor, enabling support for the Apify platform dynamically based on
APIFY_IS_AT_HOMEenv var. If you are not running the code on Apify, you don't need to use it. The method will switch storage client implementation automatically, so when you run on the Apify platform, it will use its API instead of the default memory storage. It also increases the available memory ratio from 25% to 100% on the platform.Calling
Actor.exit()is required if you use theActor.init()method, since it opens websocket connection (see Actor.events for details), which needs to be terminated for the code to finish.Graceful shutdown: When running on the Apify platform, the Actor may receive
abortingormigratingevents. By default, the SDK will automatically callActor.exit()onabortingevents andActor.reboot()onmigratingevents (to speed up the migration and continue the run on a new worker). You can disable this behavior by settingoptions.gracefulShutdowntofalse.await Actor.init();const html = await fetch('http://www.example.com').then((response) => response.text());console.log(html);await Actor.exit();Parameters
options: InitOptions = {}
Returns Promise<void>
staticisAtHome
Returns
truewhen code is running on Apify platform andfalseotherwise (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_HOMEenvironment 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 invokes the user function passed as the
userFuncparameter. - 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 immediatelyconsole.log('Hello world from Actor!');});If the user function returns a promise, it is considered asynchronous:
await Actor.main(() => {// My asynchronous function that returns a promisereturn fetch('http://www.example.com').then((response) => response.text()).then((html) => {console.log(html);});});To simplify your code, you can take advantage of the
async/awaitkeywords:await Actor.main(async () => {// My asynchronous functionconst html = await fetch('http://www.example.com').then((response) => response.text());console.log(html);});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>
- When running on the Apify platform (i.e.
staticmetamorph
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-1key in the same default key-value store.Parameters
targetActorId: string
Either
username/actor-nameor Actor ID of an Actor to which we want to metamorph.optionalinput: ActorInput
Input for the Actor. A plain object is stringified to JSON with content type
application/json; charset=utf-8. ABufferis sent as-is and needsoptions.contentType.optionaloptions: MetamorphOptions = {}
Returns Promise<void>
staticnewClient
Returns a new instance of the Apify API client. The
ApifyClientclass is provided by the apify-client NPM package, and it is automatically configured using theAPIFY_API_BASE_URL, andAPIFY_TOKENenvironment 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
options: ApifyClientOptions = {}
Returns ApifyClient
staticoff
Parameters
event: EventTypeName
optionallistener: (...args) => any
Returns void
staticon
Parameters
event: EventTypeName
listener: (...args) => 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.
Parameters
optionaldatasetIdOrName: null | StorageIdentifier
ID, name, or alias of the dataset to be opened. If
nullorundefined, the function returns the default dataset associated with the Actor run. You can also pass{ alias: 'abc' }to open a run-scoped storage,{ id: 'abc' }to open by explicit ID, or{ name: 'abc' }to open by explicit name.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 | StorageIdentifier
ID or name of the key-value store to be opened. If
nullorundefined, the function returns the default key-value store associated with the Actor run. You can also pass{ id: 'abc' }to open by explicit ID, or{ name: 'abc' }to open by explicit name.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 | StorageIdentifier
ID or name of the request queue to be opened. If
nullorundefined, the function returns the default request queue associated with the Actor run. You can also pass{ id: 'abc' }to open by explicit ID, or{ name: 'abc' }to open by explicit name.optionaloptions: OpenStorageOptions = {}
Returns Promise<RequestQueue>
staticpushData
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
awaitkeyword when callingpushData(), otherwise the Actor process might finish before the data are stored!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
options: RebootOptions = {}
Returns Promise<void>
staticresurrect
Resurrects a finished Actor run on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable).Only finished runs (SUCCEEDED, FAILED, ABORTED or TIMED-OUT) can be resurrected. The run goes back to the RUNNING status and keeps its default storages. Options you leave out keep the values of the original run.
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.resurrect(runId);Parameters
runId: string
options: ResurrectOptions = {}
Returns Promise<Run>
staticsetStatusMessage
Sets the status message for the current Actor run.
Parameters
statusMessage: string
The status message to set.
optionaloptions: SetStatusMessageOptions
Returns Promise<undefined | Run>
The updated Run object, or
undefinedwhen no run was updated: when run locally, or when the update failed or timed out (a warning is logged in that case). For more information, see the Actor Runs API endpoints.
staticsetValue
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.
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.contentTypeis specified,valuecan be any JavaScript object, and it will be stringified to JSON. - If
options.contentTypeis set,valueis taken as is, and it must be aStringorBuffer. For any other value an error will be thrown.
- If
optionaloptions: RecordOptions = {}
Returns Promise<void>
staticstart
Runs an Actor on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable), unlikeActor.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-nameor Actor ID.optionalinput: Dictionary
Input for the Actor. A plain object is stringified to JSON with content type
application/json; charset=utf-8. ABufferis sent as-is and needsoptions.contentType.optionaloptions: StartOptions = {}
Returns Promise<Run>
staticstartTask
Runs an Actor task on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable), unlikeActor.callTask, 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 Actor tasks, read the documentation.
Example usage:
const run = await Actor.startTask('bob/some-task');Parameters
taskId: string
Allowed formats are
username/task-name,userId/task-nameor 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: StartTaskOptions = {}
Returns Promise<Run>
staticuseState
Easily create and manage state values. All state values are automatically persisted.
Values can be modified by simply using the assignment operator.
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
defaultValueyou provide.optionaloptions: UseStateOptions
An optional object parameter where a custom
keyValueStoreNameandconfigcan be passed in.
Returns Promise<State>
Actorclass 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.