# Actor<!-- -->

The core class for building Actors on the Apify platform.

Actors are serverless programs running in the cloud that can perform anything from simple actions (such as filling out a web form or sending an email) to complex operations (such as crawling an entire website or removing duplicates from a large dataset). They are packaged as Docker containers which accept well-defined JSON input, perform an action, and optionally produce well-defined output.

### References

* Apify platform documentation: <https://docs.apify.com/platform/actors>
* Actor whitepaper: <https://whitepaper.actor/>

### Usage

```
import asyncio



import httpx2

from apify import Actor

from bs4 import BeautifulSoup





async def main() -> None:

    async with Actor:

        actor_input = await Actor.get_input()

        async with httpx2.AsyncClient() as client:

            response = await client.get(actor_input['url'])

        soup = BeautifulSoup(response.content, 'html.parser')

        data = {

            'url': actor_input['url'],

            'title': soup.title.string if soup.title else None,

        }

        await Actor.push_data(data)



if __name__ == '__main__':

    asyncio.run(main())
```

## Index[](#Index)

### Methods

* [\_\_aenter\_\_](https://docs.apify.com/sdk/python/reference/class/Actor.md#__aenter__)
* [\_\_aexit\_\_](https://docs.apify.com/sdk/python/reference/class/Actor.md#__aexit__)
* [\_\_call\_\_](https://docs.apify.com/sdk/python/reference/class/Actor.md#__call__)
* [\_\_init\_\_](https://docs.apify.com/sdk/python/reference/class/Actor.md#__init__)
* [\_\_repr\_\_](https://docs.apify.com/sdk/python/reference/class/Actor.md#__repr__)
* [abort](https://docs.apify.com/sdk/python/reference/class/Actor.md#abort)
* [add_webhook](https://docs.apify.com/sdk/python/reference/class/Actor.md#add_webhook)
* [call](https://docs.apify.com/sdk/python/reference/class/Actor.md#call)
* [call_task](https://docs.apify.com/sdk/python/reference/class/Actor.md#call_task)
* [charge](https://docs.apify.com/sdk/python/reference/class/Actor.md#charge)
* [configuration](https://docs.apify.com/sdk/python/reference/class/Actor.md#configuration)
* [create_proxy_configuration](https://docs.apify.com/sdk/python/reference/class/Actor.md#create_proxy_configuration)
* [event_manager](https://docs.apify.com/sdk/python/reference/class/Actor.md#event_manager)
* [exit](https://docs.apify.com/sdk/python/reference/class/Actor.md#exit)
* [exit_code](https://docs.apify.com/sdk/python/reference/class/Actor.md#exit_code)
* [fail](https://docs.apify.com/sdk/python/reference/class/Actor.md#fail)
* [get_charging_manager](https://docs.apify.com/sdk/python/reference/class/Actor.md#get_charging_manager)
* [get_env](https://docs.apify.com/sdk/python/reference/class/Actor.md#get_env)
* [get_input](https://docs.apify.com/sdk/python/reference/class/Actor.md#get_input)
* [get_value](https://docs.apify.com/sdk/python/reference/class/Actor.md#get_value)
* [init](https://docs.apify.com/sdk/python/reference/class/Actor.md#init)
* [is_at_home](https://docs.apify.com/sdk/python/reference/class/Actor.md#is_at_home)
* [metamorph](https://docs.apify.com/sdk/python/reference/class/Actor.md#metamorph)
* [new_client](https://docs.apify.com/sdk/python/reference/class/Actor.md#new_client)
* [off](https://docs.apify.com/sdk/python/reference/class/Actor.md#off)
* [on](https://docs.apify.com/sdk/python/reference/class/Actor.md#on)
* [open_dataset](https://docs.apify.com/sdk/python/reference/class/Actor.md#open_dataset)
* [open_key_value_store](https://docs.apify.com/sdk/python/reference/class/Actor.md#open_key_value_store)
* [open_request_queue](https://docs.apify.com/sdk/python/reference/class/Actor.md#open_request_queue)
* [push_data](https://docs.apify.com/sdk/python/reference/class/Actor.md#push_data)
* [reboot](https://docs.apify.com/sdk/python/reference/class/Actor.md#reboot)
* [resurrect](https://docs.apify.com/sdk/python/reference/class/Actor.md#resurrect)
* [set_status_message](https://docs.apify.com/sdk/python/reference/class/Actor.md#set_status_message)
* [set_value](https://docs.apify.com/sdk/python/reference/class/Actor.md#set_value)
* [start](https://docs.apify.com/sdk/python/reference/class/Actor.md#start)
* [start_task](https://docs.apify.com/sdk/python/reference/class/Actor.md#start_task)
* [status_message](https://docs.apify.com/sdk/python/reference/class/Actor.md#status_message)
* [use_state](https://docs.apify.com/sdk/python/reference/class/Actor.md#use_state)

### Properties

* [apify_client](https://docs.apify.com/sdk/python/reference/class/Actor.md#apify_client)
* [child_runs](https://docs.apify.com/sdk/python/reference/class/Actor.md#child_runs)
* [exit_code](https://docs.apify.com/sdk/python/reference/class/Actor.md#exit_code)
* [log](https://docs.apify.com/sdk/python/reference/class/Actor.md#log)
* [status_message](https://docs.apify.com/sdk/python/reference/class/Actor.md#status_message)

## Methods<!-- -->[](#Methods)

### [](#__aenter__)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L201)\_\_aenter\_\_

* async **\_\_aenter\_\_**(): Self

- Enter the Actor context.

  Initializes the Actor when used in an `async with` block. This method:

  * Sets up local or cloud storage clients depending on whether the Actor runs locally or on the Apify platform.
  * Configures the event manager and starts periodic state persistence.
  * Initializes the charging manager for handling charging events.
  * Loads the named child runs recorded by an earlier attempt of this Actor run.
  * On the Apify platform, forwards the status messages of Crawlee crawlers to the run status message.
  * Configures logging after all core services are registered.

  This method must be called exactly once per Actor instance. Re-initializing an Actor or having multiple active Actor instances is not standard usage and may lead to warnings or unexpected behavior.

  ***

  #### Returns Self

### [](#__aexit__)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L285)\_\_aexit\_\_

* async **\_\_aexit\_\_**(exc_type, exc_value, exc_traceback): None

- Exit the Actor context.

  If the block raises a regular exception, the Actor fails with `EXIT_CODE_ERROR_USER_FUNCTION_THREW`, unless an exit code was already set explicitly (e.g. via `fail(exit_code=...)`). A `SystemExit` keeps its own exit code, while `KeyboardInterrupt` and `asyncio.CancelledError` are re-raised after cleanup so interrupt and cancellation semantics are preserved. Otherwise, the Actor exits cleanly. In every case the Actor:

  * Stops forwarding crawler status messages to the run status message.
  * Emits the `EXIT` event.
  * Cancels periodic `PERSIST_STATE` events.
  * Sends a final `PERSIST_STATE` event.
  * Waits for all event listeners to finish.
  * Stops the event manager and the charging manager.
  * Optionally terminates the process with the selected exit code.

  ***

  #### Parameters

  * ##### exc_type: type\[BaseException] | None
  * ##### exc_value: BaseException | None
  * ##### exc_traceback: TracebackType | None

  #### Returns None

### [](#__call__)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L388)\_\_call\_\_

* **\_\_call\_\_**(configuration, \*, configure_logging, exit_process, exit_code, event_listeners_timeout, status_message, cleanup_timeout): Self

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

  This is necessary due to the lazy object proxying of the global `Actor` instance.

  ***

  #### Parameters

  * ##### optionalconfiguration: [Configuration](https://docs.apify.com/sdk/python/reference/class/Configuration.md) | None = <!-- -->None
  * ##### optionalkeyword-onlyconfigure_logging: bool = <!-- -->True
  * ##### optionalkeyword-onlyexit_process: bool | None = <!-- -->None
  * ##### optionalkeyword-onlyexit_code: int = <!-- -->0
  * ##### optionalkeyword-onlyevent_listeners_timeout: timedelta | None = <!-- -->EVENT_LISTENERS_TIMEOUT
  * ##### optionalkeyword-onlystatus_message: str | None = <!-- -->None
  * ##### optionalkeyword-onlycleanup_timeout: timedelta = <!-- -->timedelta(seconds=30)

  #### Returns Self

### [](#__init__)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L143)\_\_init\_\_

* **\_\_init\_\_**(configuration, \*, configure_logging, exit_process, exit_code, status_message, event_listeners_timeout, cleanup_timeout): None

- Initialize a new instance.

  ***

  #### Parameters

  * ##### optionalconfiguration: [Configuration](https://docs.apify.com/sdk/python/reference/class/Configuration.md) | None = <!-- -->None

    The Actor configuration to use. If not provided, a default configuration is created.

  * ##### optionalkeyword-onlyconfigure_logging: bool = <!-- -->True

    Whether to set up the default logging configuration.

  * ##### optionalkeyword-onlyexit_process: bool | None = <!-- -->None

    Whether the Actor should call `sys.exit` when the context manager exits. Defaults to True, except in IPython and Scrapy environments.

  * ##### optionalkeyword-onlyexit_code: int = <!-- -->0

    The exit code the Actor should use when exiting.

  * ##### optionalkeyword-onlystatus_message: str | None = <!-- -->None

    Final status message to display upon Actor termination.

  * ##### optionalkeyword-onlyevent_listeners_timeout: timedelta | None = <!-- -->EVENT_LISTENERS_TIMEOUT

    Maximum time to wait for Actor event listeners to complete before exiting.

  * ##### optionalkeyword-onlycleanup_timeout: timedelta = <!-- -->timedelta(seconds=30)

    Maximum time to wait for cleanup tasks to finish.

  #### Returns None

### [](#__repr__)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L382)\_\_repr\_\_

* **\_\_repr\_\_**(): str

- #### Returns str

### [](#abort)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1205)abort

* async **abort**(run_id, \*, token, status_message, gracefully): Run

- 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 Run

  Info about the aborted Actor run.

### [](#add_webhook)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1835)add_webhook

* async **add_webhook**(webhook, \*, 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](https://docs.apify.com/webhooks).

  ***

  #### Parameters

  * ##### webhook: [Webhook](https://docs.apify.com/sdk/python/reference/class/Webhook.md)

    The webhook to be added. It is automatically bound to the current Actor run.

  * ##### optionalkeyword-onlyidempotency_key: str | None = <!-- -->None

    Deprecated. Pass `idempotency_key` on the `Webhook` instance instead. Will be removed in version 5.0.0.

  #### Returns None

### [](#call)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1297)call

* async **call**(actor_id, run_input, \*, token, content_type, build, max_items, max_total_charge_usd, restart_on_error, memory_mbytes, timeout, force_permission_level, webhooks, wait, logger, run_name, abort_with_parent): Run

- 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-onlymax_items: int | None = <!-- -->None

    Deprecated, use `max_total_charge_usd` instead. Will be removed in version 5.0.0. Works only with legacy pay-per-result Actors.

  * ##### optionalkeyword-onlymax_total_charge_usd: Decimal | None = <!-- -->None

    A limit on the total charged amount, in USD. Once the run exceeds it, the platform aborts the run, which takes a few seconds, so the final charge can slightly overshoot the limit.

  * ##### optionalkeyword-onlyrestart_on_error: bool | None = <!-- -->None

    If true, the Actor run process will be restarted whenever it exits with a non-zero status code.

  * ##### 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 | Literal\[inherit]) | None = <!-- -->None

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

  * ##### optionalkeyword-onlyforce_permission_level: ActorPermissionLevel | None = <!-- -->None

    Override the Actor's permissions for this run. If not set, the Actor will run with permissions configured in the Actor settings.

  * ##### optionalkeyword-onlywebhooks: list\[[Webhook](https://docs.apify.com/sdk/python/reference/class/Webhook.md)] | 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 time the server waits for the run to finish. If not provided, waits indefinitely.

  * ##### optionalkeyword-onlylogger: (logging.Logger | Literal\[default]) | None = <!-- -->'default'

    Logger used to redirect logs from the Actor run. Using "default" literal means that a predefined default logger will be used. Setting `None` will disable any log propagation. Passing custom logger will redirect logs to the provided logger.

  * ##### optionalkeyword-onlyrun_name: str | None = <!-- -->None

    Optional name of the child run, unique within this Actor run. A named run is recorded in the default key-value store, so after a migration or resurrection of this Actor the same call reattaches to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or with a different input raises a `ValueError`. Named child runs are experimental, so their behavior and interface may change in future versions.

  * ##### optionalkeyword-onlyabort_with_parent: bool = <!-- -->False

    If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves the child running.

  #### Returns Run

  Info about the started Actor run.

### [](#call_task)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1598)call_task

* async **call_task**(task_id, task_input, \*, build, max_items, max_total_charge_usd, restart_on_error, memory_mbytes, timeout, webhooks, wait, token, run_name, abort_with_parent): Run

- 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 task 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-onlymax_items: int | None = <!-- -->None

    Deprecated, use `max_total_charge_usd` instead. Will be removed in version 5.0.0. Works only with legacy pay-per-result Actors.

  * ##### optionalkeyword-onlymax_total_charge_usd: Decimal | None = <!-- -->None

    A limit on the total charged amount, in USD. Once the run exceeds it, the platform aborts the run, which takes a few seconds, so the final charge can slightly overshoot the limit.

  * ##### optionalkeyword-onlyrestart_on_error: bool | None = <!-- -->None

    If true, the Task run process will be restarted whenever it exits with a non-zero status code.

  * ##### 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 | Literal\[inherit]) | None = <!-- -->None

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

  * ##### optionalkeyword-onlywebhooks: list\[[Webhook](https://docs.apify.com/sdk/python/reference/class/Webhook.md)] | 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 time 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).

  * ##### optionalkeyword-onlyrun_name: str | None = <!-- -->None

    Optional name of the child run, unique within this Actor run. A named run is recorded in the default key-value store, so after a migration or resurrection of this Actor the same call reattaches to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or with a different input raises a `ValueError`. Named child runs are experimental, so their behavior and interface may change in future versions.

  * ##### optionalkeyword-onlyabort_with_parent: bool = <!-- -->False

    If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves the child running.

  #### Returns Run

  Info about the started Actor run.

### [](#charge)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L944)charge

* async **charge**(event_name: str, \*: , count?
  <!-- -->
  : int, idempotency_key?
  <!-- -->
  : str | None, request_id?
  <!-- -->
  : str | None): [ChargeResult](https://docs.apify.com/sdk/python/reference/class/ChargeResult.md)
* async **charge**(event_name: str, \*: , count?
  <!-- -->
  : int, idempotency_key?
  <!-- -->
  : str | None): [ChargeResult](https://docs.apify.com/sdk/python/reference/class/ChargeResult.md)
* async **charge**(event_name: str, \*: , count?
  <!-- -->
  : int, idempotency_key?
  <!-- -->
  : str | None, request_id: str): [ChargeResult](https://docs.apify.com/sdk/python/reference/class/ChargeResult.md)

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

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

  When `count` exceeds the remaining budget, the events that fit are charged plus one more, so that the platform detects the exhausted budget and terminates the run. A run already strictly over budget charges nothing.

  ***

  #### Parameters

  * ##### event_name: str

    Name of the event to be charged for.

  * ##### optionalkeyword-onlycount: int = <!-- -->1

    Number of events to charge for.

  * ##### optionalkeyword-onlyidempotency_key: str | None = <!-- -->None

    A unique key preventing a retried operation from being charged for twice. A repeat under the same key within three minutes is not sent to the API and reports the `charged_count` of the original call, or zero if it names a different event. Like the platform, the key is forgotten afterwards. In a multi-tenant Server Actor run, every call is sent and the platform deduplicates it. The key is scoped to the whole run there, so a key reused by another caller charges only the first one - derive it from `request_id`.

  * ##### optionalkeyword-onlyrequest_id: str | None = <!-- -->None

    ID of the Server Actor request being charged, taken from the `X-Actor-Request-ID` header of the incoming request. Required in multi-tenant Server Actor runs, where it maps the charge to the caller's account instead of the account that started the run. Ignored elsewhere.

  #### Returns [ChargeResult](https://docs.apify.com/sdk/python/reference/class/ChargeResult.md)

### [](#configuration)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L466)configuration

* **configuration**(): [Configuration](https://docs.apify.com/sdk/python/reference/class/Configuration.md)

- Actor configuration, uses the default instance if not explicitly set.

  ***

  #### Returns [Configuration](https://docs.apify.com/sdk/python/reference/class/Configuration.md)

### [](#create_proxy_configuration)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1926)create_proxy_configuration

* async **create_proxy_configuration**(\*, actor_proxy_input, password, groups, country_code, subdivision_code, proxy_urls, new_url_function): [ProxyConfiguration](https://docs.apify.com/sdk/python/reference/class/ProxyConfiguration.md) | 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-onlysubdivision_code: str | None = <!-- -->None

    Subdivision (e.g. US state) which the Apify Proxy should use, if provided. Requires `country_code` to be set. 1-3 character ISO 3166-2 code of uppercase letters/digits (e.g. `CA` for California).

  * ##### 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](https://docs.apify.com/sdk/python/reference/class/ProxyConfiguration.md) | None

  ProxyConfiguration object with the passed configuration, or None, if no proxy should be used based on the configuration, or if Apify Proxy was requested in a local run that cannot use it, for example because no password is available or the proxy access is denied.

### [](#event_manager)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L487)event_manager

* **event_manager**(): EventManager

- Manages Apify platform events.

  It uses `ApifyEventManager` on the Apify platform and `LocalEventManager` otherwise.

  ***

  #### Returns EventManager

### [](#exit)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L559)exit

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

- Exit the Actor without using context-manager syntax.

  Equivalent to `await Actor.__aexit__()`.

  ***

  #### Parameters

  * ##### optionalkeyword-onlyexit_code: int = <!-- -->0

    The exit code the Actor should use when exiting.

  * ##### optionalkeyword-onlystatus_message: str | None = <!-- -->None

    Final status message to display upon Actor termination.

  * ##### optionalkeyword-onlyevent_listeners_timeout: timedelta | None = <!-- -->EVENT_LISTENERS_TIMEOUT

    Maximum time to wait for Actor event listeners to complete before exiting.

  * ##### optionalkeyword-onlycleanup_timeout: timedelta = <!-- -->timedelta(seconds=30)

    Maximum time to wait for cleanup tasks to finish.

  #### Returns None

### [](#exit_code)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L424)exit_code

* **exit_code**(value): None

- #### Parameters

  * ##### value: int

  #### Returns None

### [](#fail)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L583)fail

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

- Fail the Actor instance without using context-manager syntax.

  Equivalent to setting the `self.exit_code` and `self.status_message` properties and using `await Actor.__aexit__()`.

  ***

  #### 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)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L932)get_charging_manager

* **get_charging_manager**(): [ChargingManager](https://docs.apify.com/sdk/python/reference/class/ChargingManager.md)

- Retrieve the charging manager to access granular pricing information.

  ***

  #### Returns [ChargingManager](https://docs.apify.com/sdk/python/reference/class/ChargingManager.md)

### [](#get_env)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1058)get_env

* **get_env**(): dict

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

  Deprecated. Read `Actor.configuration` instead, or `os.environ` for variables it does not expose. Will be removed in version 5.0.0.

  For a list of all the environment variables, see the [Actor documentation](https://docs.apify.com/actors/development/environment-variables). If some variables are not defined or are invalid, the corresponding value in the resulting dictionary will be None.

  ***

  #### Returns dict

### [](#get_input)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L840)get_input

* async **get_input**(): Any

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

  The input is the deserialized contents of the input record (the `INPUT` key by default), so it is typically a `dict` keyed by the fields declared in the Actor's input schema. Any secret input fields are decrypted to plaintext before being returned.

  When running locally, the input may instead be a `<input_key>` or `<input_key>.json` file in the current working directory. A storage client that doesn't read the default key-value store's directory under the storage directory (e.g. in-memory storage) also gets the file `apify run` writes there. The input must be in exactly one place. The `.json` file is parsed as JSON; the bare file is parsed as JSON when it is valid JSON, and returned as `bytes` otherwise.

  ***

  #### Returns Any

  The Actor input, usually a `dict` of input fields, or `None` if the Actor has no input.

### [](#get_value)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L903)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.

  * ##### optionalkeyword-onlydefault_value: Any = <!-- -->None

    Default value returned in case the record does not exist.

  #### Returns Any

### [](#init)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L552)init

* async **init**(): None

- Initialize the Actor without using context-manager syntax.

  Equivalent to `await Actor.__aenter__()`.

  ***

  #### Returns None

### [](#is_at_home)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1053)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)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1719)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)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L609)new_client

* **new_client**(\*, token, api_url, api_public_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](https://github.com/apify/apify-client-python) package, and it is automatically configured using the `APIFY_API_BASE_URL`, `APIFY_API_PUBLIC_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 the `APIFY_API_BASE_URL` environment variable.

  * ##### optionalkeyword-onlyapi_public_url: str | None = <!-- -->None

    The globally accessible URL of the Apify API server, used to build public URLs of resources. Defaults to the `APIFY_API_PUBLIC_BASE_URL` environment variable.

  * ##### 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

    Baseline HTTP timeout for medium-duration API operations. The underlying client uses separate timeout tiers for short/medium/long/max-duration calls; passing a value here scales all four tiers proportionally (short = `timeout / 6`, long = `timeout * 12`, max = `timeout * 12`).

  #### Returns ApifyClientAsync

### [](#off)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1043)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)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1002)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)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L666)open_dataset

* async **open_dataset**(\*, id, alias, 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

    The ID of the dataset to open. If provided, searches for existing dataset by ID. Mutually exclusive with name and alias.

  * ##### optionalkeyword-onlyalias: str | None = <!-- -->None

    The alias of the dataset to open (run scope, creates unnamed storage). Mutually exclusive with id and name.

  * ##### optionalkeyword-onlyname: str | None = <!-- -->None

    The name of the dataset to open (global scope, persists across runs). Mutually exclusive with id and alias.

  * ##### 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

  An instance of the `Dataset` class for the given ID or name.

### [](#open_key_value_store)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L701)open_key_value_store

* async **open_key_value_store**(\*, id, alias, 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

    The ID of the KVS to open. If provided, searches for existing KVS by ID. Mutually exclusive with name and alias.

  * ##### optionalkeyword-onlyalias: str | None = <!-- -->None

    The alias of the KVS to open (run scope, creates unnamed storage). Mutually exclusive with id and name.

  * ##### optionalkeyword-onlyname: str | None = <!-- -->None

    The name of the KVS to open (global scope, persists across runs). Mutually exclusive with id and alias.

  * ##### 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

  An instance of the `KeyValueStore` class for the given ID or name.

### [](#open_request_queue)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L735)open_request_queue

* async **open_request_queue**(\*, id, alias, 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

    The ID of the RQ to open. If provided, searches for existing RQ by ID. Mutually exclusive with name and alias.

  * ##### optionalkeyword-onlyalias: str | None = <!-- -->None

    The alias of the RQ to open (run scope, creates unnamed storage). Mutually exclusive with id and name.

  * ##### optionalkeyword-onlyname: str | None = <!-- -->None

    The name of the RQ to open (global scope, persists across runs). Mutually exclusive with id and alias.

  * ##### 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

  An instance of the `RequestQueue` class for the given ID or name.

### [](#push_data)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L771)push_data

* async **push_data**(data, \*, charged_event_name): [ChargeResult](https://docs.apify.com/sdk/python/reference/class/ChargeResult.md)

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

  * ##### optionalkeyword-onlycharged_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. Not supported in multi-tenant Server Actor runs, which charge per request with `Actor.charge()`.

  #### Returns [ChargeResult](https://docs.apify.com/sdk/python/reference/class/ChargeResult.md)

### [](#reboot)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1766)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

### [](#resurrect)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1242)resurrect

* async **resurrect**(run_id, \*, token, build, memory_mbytes, timeout, max_items, max_total_charge_usd, restart_on_error): Run

- Resurrect a finished Actor run on the Apify platform.

  Only finished runs, i.e. runs with status SUCCEEDED, FAILED, ABORTED and TIMED-OUT, can be resurrected. The run status is set back to RUNNING and its container is restarted with the same default storages.

  ***

  #### Parameters

  * ##### run_id: str

    The ID of the Actor run to be resurrected.

  * ##### optionalkeyword-onlytoken: str | None = <!-- -->None

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

  * ##### optionalkeyword-onlybuild: str | None = <!-- -->None

    Which Actor build the resurrected run should use. It can be either a build tag or build number. By default, the resurrected run uses the same build as before.

  * ##### optionalkeyword-onlymemory_mbytes: int | None = <!-- -->None

    New memory limit for the resurrected run, in megabytes. By default, the resurrected run uses the same memory limit as before.

  * ##### optionalkeyword-onlytimeout: (timedelta | Literal\[inherit]) | None = <!-- -->None

    New timeout for the resurrected run. By default, the resurrected run uses the same timeout as before. Using `inherit` will set timeout of the resurrected run to the time remaining from this Actor timeout.

  * ##### optionalkeyword-onlymax_items: int | None = <!-- -->None

    Deprecated, use `max_total_charge_usd` instead. Will be removed in version 5.0.0. Works only with legacy pay-per-result Actors. By default, the resurrected run uses the same limit as before. The limit can only be increased.

  * ##### optionalkeyword-onlymax_total_charge_usd: Decimal | None = <!-- -->None

    A limit on the total charged amount of the resurrected run, in USD. Once the run exceeds it, the platform aborts the run, which takes a few seconds, so the final charge can slightly overshoot the limit. By default, the resurrected run uses the same limit as before. The limit can only be increased.

  * ##### optionalkeyword-onlyrestart_on_error: bool | None = <!-- -->None

    If true, the resurrected run process will be restarted whenever it exits with a non-zero status code. By default, the resurrected run uses the same setting as before.

  #### Returns Run

  Info about the resurrected Actor run.

### [](#set_status_message)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1881)set_status_message

* async **set_status_message**(status_message, \*, is_terminal): Run | None

- Set the status message for the current Actor run.

  The status message is cosmetic, so a failed or timed-out update is logged as a warning and never raises.

  ***

  #### 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 Run | None

  The updated Actor run object, or `None` when no run was updated: when running locally, or when the update failed or timed out.

### [](#set_value)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L914)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)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1097)start

* async **start**(actor_id, run_input, \*, token, content_type, build, max_items, max_total_charge_usd, restart_on_error, memory_mbytes, timeout, force_permission_level, webhooks, run_name, abort_with_parent): Run

- Run an Actor on the Apify platform.

  Unlike `Actor.call`, this method just starts the run without waiting for finish. To wait for the run to finish, use `Actor.call` instead.

  ***

  #### 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-onlymax_items: int | None = <!-- -->None

    Deprecated, use `max_total_charge_usd` instead. Will be removed in version 5.0.0. Works only with legacy pay-per-result Actors.

  * ##### optionalkeyword-onlymax_total_charge_usd: Decimal | None = <!-- -->None

    A limit on the total charged amount, in USD. Once the run exceeds it, the platform aborts the run, which takes a few seconds, so the final charge can slightly overshoot the limit.

  * ##### optionalkeyword-onlyrestart_on_error: bool | None = <!-- -->None

    If true, the Actor run process will be restarted whenever it exits with a non-zero status code.

  * ##### 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 | Literal\[inherit]) | None = <!-- -->None

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

  * ##### optionalkeyword-onlyforce_permission_level: ActorPermissionLevel | None = <!-- -->None

    Override the Actor's permissions for this run. If not set, the Actor will run with permissions configured in the Actor settings.

  * ##### optionalkeyword-onlywebhooks: list\[[Webhook](https://docs.apify.com/sdk/python/reference/class/Webhook.md)] | 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.

  * ##### optionalkeyword-onlyrun_name: str | None = <!-- -->None

    Optional name of the child run, unique within this Actor run. A named run is recorded in the default key-value store, so after a migration or resurrection of this Actor the same call reattaches to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or with a different input raises a `ValueError`. Named child runs are experimental, so their behavior and interface may change in future versions.

  * ##### optionalkeyword-onlyabort_with_parent: bool = <!-- -->False

    If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves the child running.

  #### Returns Run

  Info about the started Actor run

### [](#start_task)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1495)start_task

* async **start_task**(task_id, task_input, \*, build, max_items, max_total_charge_usd, restart_on_error, memory_mbytes, timeout, webhooks, token, run_name, abort_with_parent): Run

- Start an Actor task on the Apify Platform.

  Unlike `Actor.call_task`, this method just starts the run without waiting for finish. To wait for the run to finish, use `Actor.call_task` instead.

  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, use `Actor.start`.

  ***

  #### Parameters

  * ##### task_id: str

    The ID of the Actor task 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-onlymax_items: int | None = <!-- -->None

    Deprecated, use `max_total_charge_usd` instead. Will be removed in version 5.0.0. Works only with legacy pay-per-result Actors.

  * ##### optionalkeyword-onlymax_total_charge_usd: Decimal | None = <!-- -->None

    A limit on the total charged amount, in USD. Once the run exceeds it, the platform aborts the run, which takes a few seconds, so the final charge can slightly overshoot the limit.

  * ##### optionalkeyword-onlyrestart_on_error: bool | None = <!-- -->None

    If true, the Task run process will be restarted whenever it exits with a non-zero status code.

  * ##### 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 | Literal\[inherit]) | None = <!-- -->None

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

  * ##### optionalkeyword-onlywebhooks: list\[[Webhook](https://docs.apify.com/sdk/python/reference/class/Webhook.md)] | 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-onlytoken: str | None = <!-- -->None

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

  * ##### optionalkeyword-onlyrun_name: str | None = <!-- -->None

    Optional name of the child run, unique within this Actor run. A named run is recorded in the default key-value store, so after a migration or resurrection of this Actor the same call reattaches to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or with a different input raises a `ValueError`. Named child runs are experimental, so their behavior and interface may change in future versions.

  * ##### optionalkeyword-onlyabort_with_parent: bool = <!-- -->False

    If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves the child running.

  #### Returns Run

  Info about the started Actor run.

### [](#status_message)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L433)status_message

* **status_message**(value): None

- #### Parameters

  * ##### value: str | None

  #### Returns None

### [](#use_state)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L1991)use_state

* async **use_state**(default_value, \*, key, kvs_name): MutableMapping\[str, JsonSerializable]

- Easily create and manage state values. All state values are automatically persisted.

  Values can be modified by simply using the assignment operator.

  ***

  #### Parameters

  * ##### optionaldefault_value: dict\[str, JsonSerializable] | None = <!-- -->None

    The default value to initialize the state if it is not already set.

  * ##### optionalkeyword-onlykey: str | None = <!-- -->None

    The key in the key-value store where the state is stored. If not provided, a default key is used.

  * ##### optionalkeyword-onlykvs_name: str | None = <!-- -->None

    The name of the key-value store where the state is stored. If not provided, the default key-value store associated with the Actor run is used.

  #### Returns MutableMapping\[str, JsonSerializable]

  The state dictionary with automatic persistence.

## Properties<!-- -->[](#Properties)

### [](#apify_client)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L437)apify_client

apify_client: ApifyClientAsync

Asynchronous Apify client for interacting with the Apify API.

### [](#child_runs)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L445)child_runs

child_runs: dict\[str, RunClientAsync]

Clients for the named child runs of this Actor run, keyed by the run name.

Every run started by `Actor.start`, `Actor.call`, `Actor.start_task` or `Actor.call_task` with a `run_name` is included, even one started before a migration or resurrection of this Actor run. Runs started without a `run_name` are not tracked. Each client points to the current run under its name:

```
run = await Actor.child_runs['my-child'].wait_for_finish()
```

A run started or reattached with a custom `token` since the last migration or resurrection of this Actor run uses that token. Any other run uses the default client.

Warning

This is an experimental feature. The behavior and interface may change in future versions.

### [](#exit_code)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L419)exit_code

exit_code: int

The exit code the Actor will use when exiting.

### [](#log)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L414)log

log: logging.Logger

Logger configured for this Actor.

### [](#status_message)[](https://github.com/apify/apify-sdk-python/blob/c674a4d42ade9c1a07f33062b6702497cd34b19d//src/apify/_actor.py#L428)status_message

status_message: str | None

The final status message that the Actor will display upon termination.
