Skip to main content

Actor

The class of Actor. Only make a new instance if you're absolutely sure you need to.

Index

Methods

Properties

Methods

__call__

  • __call__(configuration, *, configure_logging, exit_process): Self

  • Make a new Actor instance with a non-default configuration.

    Parameters

    • optionalconfiguration: Configuration | None = None
    • optionalkeyword-onlyconfigure_logging: bool = True
    • optionalkeyword-onlyexit_process: bool | None = None

    Returns Self

__init__

  • __init__(configuration, *, configure_logging, exit_process): None

  • Create an Actor instance.

    Note that you don't have to do this, all the functionality is accessible using the default instance (e.g. Actor.open_dataset()).

    Parameters

    • optionalconfiguration: Configuration | None = None

      The Actor configuration to be used. If not passed, a new Configuration instance will be created.

    • optionalkeyword-onlyconfigure_logging: bool = True

      Should the default logging configuration be configured?

    • optionalkeyword-onlyexit_process: bool | None = None

      Whether the Actor should call sys.exit when the context manager exits. The default is True except for the IPython, Pytest and Scrapy environments.

    Returns None

__repr__

  • __repr__(): str

  • Returns str

abort

  • async abort(run_id, *, token, status_message, gracefully): ActorRun

  • Abort given Actor run on the Apify platform using the current user account.

    The user account is determined by the APIFY_TOKEN environment variable.

    Parameters

    • run_id: str

      The ID of the Actor run to be aborted.

    • optionalkeyword-onlytoken: str | None = None

      The Apify API token to use for this request (defaults to the APIFY_TOKEN environment variable).

    • optionalkeyword-onlystatus_message: str | None = None

      Status message of the Actor to be set on the platform.

    • optionalkeyword-onlygracefully: bool | None = None

      If True, the Actor run will abort gracefully. It will send aborting and persistState events into the run and force-stop the run after 30 seconds. It is helpful in cases where you plan to resurrect the run later.

    Returns ActorRun

add_webhook

  • async add_webhook(webhook, *, ignore_ssl_errors, do_not_retry, idempotency_key): None

  • Create an ad-hoc webhook for the current Actor run.

    This webhook lets you receive a notification when the Actor run finished or failed.

    Note that webhooks are only supported for Actors running on the Apify platform. When running the Actor locally, the function will print a warning and have no effect.

    For more information about Apify Actor webhooks, please see the documentation.

    Parameters

    • webhook: Webhook

      The webhook to be added

    • optionalkeyword-onlyignore_ssl_errors: bool | None = None

      Whether the webhook should ignore SSL errors returned by request_url

    • optionalkeyword-onlydo_not_retry: bool | None = None

      Whether the webhook should retry sending the payload to request_url upon failure.

    • optionalkeyword-onlyidempotency_key: str | None = None

      A unique identifier of a webhook. You can use it to ensure that you won't create the same webhook multiple times.

    Returns None

call

  • async call(actor_id, run_input, *, token, content_type, build, memory_mbytes, timeout, webhooks, wait): ActorRun | None

  • Start an Actor on the Apify Platform and wait for it to finish before returning.

    It waits indefinitely, unless the wait argument is provided.

    Parameters

    • actor_id: str

      The ID of the Actor to be run.

    • optionalrun_input: Any = None

      The input to pass to the Actor run.

    • optionalkeyword-onlytoken: str | None = None

      The Apify API token to use for this request (defaults to the APIFY_TOKEN environment variable).

    • optionalkeyword-onlycontent_type: str | None = None

      The content type of the input.

    • optionalkeyword-onlybuild: str | None = None

      Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

    • optionalkeyword-onlymemory_mbytes: int | None = None

      Memory limit for the run, in megabytes. By default, the run uses a memory limit specified in the default run configuration for the Actor.

    • optionalkeyword-onlytimeout: (timedelta | None) | Literal[RemainingTime] = None

      Optional timeout for the run, in seconds. By default, the run uses timeout specified in the default run configuration for the Actor. Using RemainingTime will set timeout of the other Actor to the time remaining from this Actor timeout.

    • optionalkeyword-onlywebhooks: list[Webhook] | None = None

      Optional webhooks (https://docs.apify.com/webhooks) associated with the Actor run, which can be used to receive a notification, e.g. when the Actor finished or failed. If you already have a webhook set up for the Actor, you do not have to add it again here.

    • optionalkeyword-onlywait: timedelta | None = None

      The maximum number of seconds the server waits for the run to finish. If not provided, waits indefinitely.

    Returns ActorRun | None

call_task

  • async call_task(task_id, task_input, *, build, memory_mbytes, timeout, webhooks, wait, token): ActorRun | None

  • Start an Actor task on the Apify Platform and wait for it to finish before returning.

    It waits indefinitely, unless the wait argument is provided.

    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

    Parameters

    • task_id: str

      The ID of the Actor to be run.

    • optionaltask_input: dict | None = None

      Overrides the input to pass to the Actor run.

    • optionalkeyword-onlybuild: str | None = None

      Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

    • optionalkeyword-onlymemory_mbytes: int | None = None

      Memory limit for the run, in megabytes. By default, the run uses a memory limit specified in the default run configuration for the Actor.

    • optionalkeyword-onlytimeout: timedelta | None = None

      Optional timeout for the run, in seconds. By default, the run uses timeout specified in the default run configuration for the Actor.

    • optionalkeyword-onlywebhooks: list[Webhook] | None = None

      Optional webhooks (https://docs.apify.com/webhooks) associated with the Actor run, which can be used to receive a notification, e.g. when the Actor finished or failed. If you already have a webhook set up for the Actor, you do not have to add it again here.

    • optionalkeyword-onlywait: timedelta | None = None

      The maximum number of seconds the server waits for the run to finish. If not provided, waits indefinitely.

    • optionalkeyword-onlytoken: str | None = None

      The Apify API token to use for this request (defaults to the APIFY_TOKEN environment variable).

    Returns ActorRun | None

charge

  • Charge for a specified number of events - sub-operations of the Actor.

    This is relevant only for the pay-per-event pricing model.

    Parameters

    • event_name: str

      Name of the event to be charged for.

    • optionalcount: int = 1

      Number of events to charge for.

    Returns ChargeResult

create_proxy_configuration

  • async create_proxy_configuration(*, actor_proxy_input, password, groups, country_code, proxy_urls, new_url_function): ProxyConfiguration | None

  • Create a ProxyConfiguration object with the passed proxy configuration.

    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.

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

    Parameters

    • optionalkeyword-onlyactor_proxy_input: dict | None = None

      Proxy configuration field from the Actor input, if input has such input field. If you pass this argument, all the other arguments will be inferred from it.

    • optionalkeyword-onlypassword: str | None = None

      Password for the Apify Proxy. If not provided, will use os.environ['APIFY_PROXY_PASSWORD'], if available.

    • optionalkeyword-onlygroups: list[str] | None = None

      Proxy groups which the Apify Proxy should use, if provided.

    • optionalkeyword-onlycountry_code: str | None = None

      Country which the Apify Proxy should use, if provided.

    • optionalkeyword-onlyproxy_urls: list[str | None] | None = None

      Custom proxy server URLs which should be rotated through.

    • optionalkeyword-onlynew_url_function: _NewUrlFunction | None = None

      Function which returns a custom proxy URL to be used.

    Returns ProxyConfiguration | None

exit

  • async exit(*, exit_code, event_listeners_timeout, status_message, cleanup_timeout): None

  • Exit the Actor instance.

    This stops the Actor instance. It cancels all the intervals for regularly sending PERSIST_STATE events, sends a final PERSIST_STATE event, waits for all the event listeners to finish, and stops the event manager.

    Parameters

    • optionalkeyword-onlyexit_code: int = 0

      The exit code with which the Actor should fail (defaults to 0).

    • optionalkeyword-onlyevent_listeners_timeout: timedelta | None = EVENT_LISTENERS_TIMEOUT

      How long should the Actor wait for Actor event listeners to finish before exiting.

    • optionalkeyword-onlystatus_message: str | None = None

      The final status message that the Actor should display.

    • optionalkeyword-onlycleanup_timeout: timedelta = timedelta(seconds=30)

      How long we should wait for event listeners.

    Returns None

fail

  • async fail(*, exit_code, exception, status_message): None

  • Fail the Actor instance.

    This performs all the same steps as Actor.exit(), but it additionally sets the exit code to 1 (by default).

    Parameters

    • optionalkeyword-onlyexit_code: int = 1

      The exit code with which the Actor should fail (defaults to 1).

    • optionalkeyword-onlyexception: BaseException | None = None

      The exception with which the Actor failed.

    • optionalkeyword-onlystatus_message: str | None = None

      The final status message that the Actor should display.

    Returns None

get_charging_manager

  • Retrieve the charging manager to access granular pricing information.

    Returns ChargingManager

get_env

  • get_env(): dict

  • Return a dictionary with information parsed from all the APIFY_XXX environment variables.

    For a list of all the environment variables, see the Actor documentation. If some variables are not defined or are invalid, the corresponding value in the resulting dictionary will be None.

    Returns dict

get_input

  • async get_input(): Any

  • Get the Actor input value from the default key-value store associated with the current Actor run.

    Returns Any

get_value

  • async get_value(key, default_value): Any

  • Get a value from the default key-value store associated with the current Actor run.

    Parameters

    • key: str

      The key of the record which to retrieve.

    • optionaldefault_value: Any = None

      Default value returned in case the record does not exist.

    Returns Any

init

  • async init(): None

  • Initialize the Actor instance.

    This initializes the Actor instance. It configures the right storage client based on whether the Actor is running locally or on the Apify platform, it initializes the event manager for processing Actor events, and starts an interval for regularly sending PERSIST_STATE events, so that the Actor can regularly persist its state in response to these events.

    This method should be called immediately before performing any additional Actor actions, and it should be called only once.

    Returns None

is_at_home

  • is_at_home(): bool

  • Return True when the Actor is running on the Apify platform, and False otherwise (e.g. local run).

    Returns bool

metamorph

  • async metamorph(target_actor_id, run_input, *, target_actor_build, content_type, custom_after_sleep): None

  • Transform this Actor run to an Actor run of a different Actor.

    The platform stops the current Actor container and starts a new container with the new Actor 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

    • target_actor_id: str

      ID of the target Actor that the run should be transformed into

    • optionalrun_input: Any = None

      The input to pass to the new run.

    • optionalkeyword-onlytarget_actor_build: str | None = None

      The build of the target Actor. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the target Actor (typically the latest build).

    • optionalkeyword-onlycontent_type: str | None = None

      The content type of the input.

    • optionalkeyword-onlycustom_after_sleep: timedelta | None = None

      How long to sleep for after the metamorph, to wait for the container to be stopped.

    Returns None

new_client

  • new_client(*, token, api_url, max_retries, min_delay_between_retries, timeout): ApifyClientAsync

  • Return a new instance of the Apify API client.

    The ApifyClientAsync class is provided by the apify-client 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

    • optionalkeyword-onlytoken: str | None = None

      The Apify API token.

    • optionalkeyword-onlyapi_url: str | None = None

      The URL of the Apify API server to which to connect to. Defaults to https://api.apify.com.

    • optionalkeyword-onlymax_retries: int | None = None

      How many times to retry a failed request at most.

    • optionalkeyword-onlymin_delay_between_retries: timedelta | None = None

      How long will the client wait between retrying requests (increases exponentially from this value).

    • optionalkeyword-onlytimeout: timedelta | None = None

      The socket timeout of the HTTP requests sent to the Apify API.

    Returns ApifyClientAsync

off

  • off(event_name: Event, listener?: Callable | None): None
  • off(event_name: Literal[Event.PERSIST_STATE], listener: EventListener[EventPersistStateData]): None
  • off(event_name: Literal[Event.SYSTEM_INFO], listener: EventListener[EventSystemInfoData]): None
  • off(event_name: Literal[Event.MIGRATING], listener: EventListener[EventMigratingData]): None
  • off(event_name: Literal[Event.ABORTING], listener: EventListener[EventAbortingData]): None
  • off(event_name: Literal[Event.EXIT], listener: EventListener[EventExitData]): None
  • off(event_name: Event, listener: EventListener[None]): None

  • Remove a listener, or all listeners, from an Actor event.

    Parameters

    • event_name: Event

      The Actor event for which to remove listeners.

    • optionallistener: Callable | None = None

      The listener which is supposed to be removed. If not passed, all listeners of this event are removed.

    Returns None

on

  • on(event_name: Event, listener: EventListener[Any]): EventListener[Any]
  • on(event_name: Literal[Event.PERSIST_STATE], listener: EventListener[EventPersistStateData]): EventListener[EventPersistStateData]
  • on(event_name: Literal[Event.SYSTEM_INFO], listener: EventListener[EventSystemInfoData]): EventListener[EventSystemInfoData]
  • on(event_name: Literal[Event.MIGRATING], listener: EventListener[EventMigratingData]): EventListener[EventMigratingData]
  • on(event_name: Literal[Event.ABORTING], listener: EventListener[EventAbortingData]): EventListener[EventAbortingData]
  • on(event_name: Literal[Event.EXIT], listener: EventListener[EventExitData]): EventListener[EventExitData]
  • on(event_name: Event, listener: EventListener[None]): EventListener[Any]

  • Add an event listener to the Actor's event manager.

    The following events can be emitted:

    • Event.SYSTEM_INFO: Emitted every minute; the event data contains information about the Actor's resource usage.
    • Event.MIGRATING: Emitted when the Actor on the Apify platform is about to be migrated to another worker server. Use this event to persist the Actor's state and gracefully stop in-progress tasks, preventing disruption.
    • Event.PERSIST_STATE: Emitted regularly (default: 60 seconds) to notify the Actor to persist its state, preventing work repetition after a restart. This event is emitted together with the MIGRATING event, where the isMigrating flag in the event data is True; otherwise, the flag is False. This event is for convenience; the same effect can be achieved by setting an interval and listening for the MIGRATING event.
    • Event.ABORTING: Emitted when a user aborts an Actor run on the Apify platform, allowing the Actor time to clean up its state if the abort is graceful.

    Parameters

    • event_name: Event

      The Actor event to listen for.

    • listener: EventListener[Any]

      The function to be called when the event is emitted (can be async).

    Returns EventListener[Any]

open_dataset

  • async open_dataset(*, id, name, force_cloud): Dataset

  • Open a dataset.

    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 Apify cloud.

    Parameters

    • optionalkeyword-onlyid: str | None = None

      ID of the dataset to be opened. If neither id nor name are provided, the method returns the default dataset associated with the Actor run.

    • optionalkeyword-onlyname: str | None = None

      Name of the dataset to be opened. If neither id nor name are provided, the method returns the default dataset associated with the Actor run.

    • optionalkeyword-onlyforce_cloud: bool = False

      If set to True then the Apify cloud storage is always used. This way it is possible to combine local and cloud storage.

    Returns Dataset

open_key_value_store

  • async open_key_value_store(*, id, name, force_cloud): KeyValueStore

  • Open a key-value store.

    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.

    Parameters

    • optionalkeyword-onlyid: str | None = None

      ID of the key-value store to be opened. If neither id nor name are provided, the method returns the default key-value store associated with the Actor run.

    • optionalkeyword-onlyname: str | None = None

      Name of the key-value store to be opened. If neither id nor name are provided, the method returns the default key-value store associated with the Actor run.

    • optionalkeyword-onlyforce_cloud: bool = False

      If set to True then the Apify cloud storage is always used. This way it is possible to combine local and cloud storage.

    Returns KeyValueStore

open_request_queue

  • async open_request_queue(*, id, name, force_cloud): RequestQueue

  • Open a request queue.

    Request queue represents a queue of URLs to crawl, which is stored either on local filesystem or in the Apify 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.

    Parameters

    • optionalkeyword-onlyid: str | None = None

      ID of the request queue to be opened. If neither id nor name are provided, the method returns the default request queue associated with the Actor run.

    • optionalkeyword-onlyname: str | None = None

      Name of the request queue to be opened. If neither id nor name are provided, the method returns the default request queue associated with the Actor run.

    • optionalkeyword-onlyforce_cloud: bool = False

      If set to True then the Apify cloud storage is always used. This way it is possible to combine local and cloud storage.

    Returns RequestQueue

push_data

  • async push_data(data: dict | list[dict], charged_event_name?: str | None): ChargeResult | None
  • async push_data(data: dict | list[dict]): None
  • async push_data(data: dict | list[dict], charged_event_name: str): ChargeResult

  • Store an object or a list of objects to the default dataset of the current Actor run.

    Parameters

    • data: dict | list[dict]

      The data to push to the default dataset.

    • optionalcharged_event_name: str | None = None

      If provided and if the Actor uses the pay-per-event pricing model, the method will attempt to charge for the event for each pushed item.

    Returns ChargeResult | None

reboot

  • async reboot(*, event_listeners_timeout, custom_after_sleep): None

  • Internally reboot this Actor.

    The system stops the current container and starts a new one, with the same run ID and default storages.

    Parameters

    • optionalkeyword-onlyevent_listeners_timeout: timedelta | None = EVENT_LISTENERS_TIMEOUT

      How long should the Actor wait for Actor event listeners to finish before exiting.

    • optionalkeyword-onlycustom_after_sleep: timedelta | None = None

      How long to sleep for after the reboot, to wait for the container to be stopped.

    Returns None

set_status_message

  • async set_status_message(status_message, *, is_terminal): ActorRun | None

  • Set the status message for the current Actor run.

    Parameters

    • status_message: str

      The status message to set to the run.

    • optionalkeyword-onlyis_terminal: bool | None = None

      Set this flag to True if this is the final status message of the Actor run.

    Returns ActorRun | None

set_value

  • async set_value(key, value, *, content_type): None

  • Set or delete a value in the default key-value store associated with the current Actor run.

    Parameters

    • key: str

      The key of the record which to set.

    • value: Any

      The value of the record which to set, or None, if the record should be deleted.

    • optionalkeyword-onlycontent_type: str | None = None

      The content type which should be set to the value.

    Returns None

start

  • async start(actor_id, run_input, *, token, content_type, build, memory_mbytes, timeout, wait_for_finish, webhooks): ActorRun

  • Run an Actor on the Apify platform.

    Unlike Actor.call, this method just starts the run without waiting for finish.

    Parameters

    • actor_id: str

      The ID of the Actor to be run.

    • optionalrun_input: Any = None

      The input to pass to the Actor run.

    • optionalkeyword-onlytoken: str | None = None

      The Apify API token to use for this request (defaults to the APIFY_TOKEN environment variable).

    • optionalkeyword-onlycontent_type: str | None = None

      The content type of the input.

    • optionalkeyword-onlybuild: str | None = None

      Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

    • optionalkeyword-onlymemory_mbytes: int | None = None

      Memory limit for the run, in megabytes. By default, the run uses a memory limit specified in the default run configuration for the Actor.

    • optionalkeyword-onlytimeout: (timedelta | None) | Literal[RemainingTime] = None

      Optional timeout for the run, in seconds. By default, the run uses timeout specified in the default run configuration for the Actor. Using RemainingTime will set timeout of the other Actor to the time remaining from this Actor timeout.

    • optionalkeyword-onlywait_for_finish: int | None = None

      The maximum number of seconds the server waits for the run to finish. By default, it is 0, the maximum value is 300.

    • optionalkeyword-onlywebhooks: list[Webhook] | None = None

      Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed. If you already have a webhook set up for the Actor or task, you do not have to add it again here.

    Returns ActorRun

Properties

apify_client

apify_client: ApifyClientAsync

The ApifyClientAsync instance the Actor instance uses.

config

config: Configuration

The Configuration instance the Actor instance uses.

configuration

configuration: Configuration

The Configuration instance the Actor instance uses.

event_manager

event_manager: EventManager

The EventManager instance the Actor instance uses.

log

log: logging.Logger

The logging.Logger instance the Actor uses.

Page Options