---
title: "API reference · Scrape.ly Docs"
description: "Every Actor method, option class, and root export."
url: https://scrape.ly/docs/sdk-python-reference
markdown: https://scrape.ly/docs/sdk-python-reference.md
---

# API reference

> Every Actor method, option class, and root export.

This page lists the full `Actor` API and every root export of the `scrapely` package, with signatures taken from the SDK source. For explanations and examples, follow the topic pages linked from the [SDK overview](https://scrape.ly/docs/sdk-python.md).

Every method below is a classmethod on `Actor`. Methods marked async are coroutines, so you must await them.

## Lifecycle

| Member | Signature | Async |
| --- | --- | --- |
| `Actor(...)` | `Actor(options=None, *, configure_logging=True, exit_code=0, status_message=None, cleanup_timeout=timedelta(seconds=30), exit_process=None, event_listeners_timeout=None)` | context manager |
| `init` | `init(options: InitOptions \| None = None) -> None` | async |
| `main` | `main(user_func: Callable[[], Awaitable]) -> Any`. Always ends with `sys.exit()` | async |
| `exit` | `exit(message_or_options=None, options: ExitOptions \| None = None, *, status_message=None, exit_code=None) -> None` | async |
| `fail` | `fail(message_or_options=None, options: ExitOptions \| None = None, *, status_message=None, exit_code=None) -> None` | async |
| `get_default_instance` | `get_default_instance() -> Actor` | sync |

`async with Actor:` and `async with Actor(...):` call `init()` on entry and shut down on exit. Neither form calls `sys.exit()`. See [Lifecycle](https://scrape.ly/docs/sdk-python-lifecycle.md).

## Input and output

| Member | Signature | Async |
| --- | --- | --- |
| `get_input` | `get_input() -> dict \| None` | async |
| `get_input_or_throw` | `get_input_or_throw() -> dict` | async |
| `input` | property `-> dict \| None` | sync |
| `push_data` | `push_data(data: dict \| list[dict], charged_event_name: str \| None = None, *, event_name: str \| None = None) -> ChargeResult` | async |
| `get_value` | `get_value(key: str, default_value: Any = None) -> Any` | async |
| `set_value` | `set_value(key: str, value: Any, content_type: str \| None = None) -> None` | async |

## Storages

| Member | Signature | Async |
| --- | --- | --- |
| `open_dataset` | `open_dataset(name_or_id=None, options: OpenStorageOptions \| None = None, *, id=None, name=None, alias=None, force_cloud=False) -> Dataset` | async |
| `open_key_value_store` | same arguments `-> KeyValueStore` | async |
| `open_request_queue` | same arguments `-> RequestQueue` | async |

## Events, state and status

| Member | Signature | Async |
| --- | --- | --- |
| `on` | `on(event: Event, listener) -> None` | sync |
| `off` | `off(event: Event, listener=None) -> None` | sync |
| `use_state` | `use_state(default_value: dict \| None = None, key: str \| None = None, kvs_name: str \| None = None) -> MutableMapping[str, Any]` | async |
| `reboot` | `reboot(options: RebootOptions \| None = None) -> None` | async |
| `set_status_message` | `set_status_message(message: str, options: SetStatusMessageOptions \| None = None, *, is_terminal: bool \| None = None) -> ActorRun` | async |

## Runs and webhooks

| Member | Signature | Async |
| --- | --- | --- |
| `start` | `start(actor_id: str, run_input=None, options: StartOptions \| None = None) -> ActorRun` | async |
| `call` | `call(actor_id: str, run_input=None, options: CallOptions \| None = None) -> ActorRun` | async |
| `call_task` | `call_task(task_id: str, task_input: dict \| None = None, options: CallOptions \| None = None) -> ActorRun` | async |
| `abort` | `abort(run_id: str \| None = None, options: AbortOptions \| None = None) -> ActorRun` | async |
| `metamorph` | `metamorph(target_actor_id: str, run_input=None, options: MetamorphOptions \| None = None) -> None` | async |
| `add_webhook` | `add_webhook(webhook: Webhook) -> Webhook \| None` | async |

## Charging

| Member | Signature | Async |
| --- | --- | --- |
| `charge` | `charge(event_name: str, count: int = 1) -> ChargeResult` | async |
| `get_charging_manager` | `get_charging_manager() -> ChargingManager` | sync |

For the `ChargingManager` methods, see [Actors & webhooks](https://scrape.ly/docs/sdk-python-actors.md#charging-manager).

## Proxy and browser

| Member | Signature | Async |
| --- | --- | --- |
| `create_proxy_configuration` | `create_proxy_configuration(actor_proxy_input=None, password=None, groups=None, country_code=None, subdivision_code=None, proxy_urls=None, new_url_function=None, tiered_proxy_urls=None, tiered_proxy_config=None, check_access=True) -> ProxyConfiguration \| None` | async |
| `create_browser_configuration` | `create_browser_configuration(actor_browser_input=None, *, country_code=None, state=None, city=None, os=None, timezone=None, language=None, adblock=None, solve_cloudflare=None) -> BrowserConfiguration` | async |

## Environment and clients

| Member | Signature | Async |
| --- | --- | --- |
| `is_at_home` | `is_at_home() -> bool` | sync |
| `is_standby` | `is_standby() -> bool` | sync |
| `is_paying` | property `-> bool` | sync |
| `get_env` | `get_env() -> ApifyEnv` | sync |
| `get_remaining_time` | `get_remaining_time() -> int \| None` (milliseconds) | sync |
| `get_config` | `get_config() -> Configuration` | sync |
| `configuration` | property `-> Configuration` | sync |
| `event_manager` | property `-> EventManager \| None` | sync |
| `log` | property `-> logging.Logger` | sync |
| `exit_code` | property `-> int` | sync |
| `status_message` | property `-> str \| None` | sync |
| `new_client` | `new_client(token=None, base_url=None) -> scrapely.storage.ApiClient` | sync |
| `apify_client` | property `-> scrapely_client.ApifyClientAsync` | sync |

`apify_client` comes from `scrapely-client-python`. See the [Python API client](https://scrape.ly/docs/client-python.md).

## Option classes

| Class | Fields (defaults) |
| --- | --- |
| `InitOptions` | `configuration=None`, `storage=None`, `graceful_shutdown=True` (unused), `graceful_shutdown_delay_millis=0` (unused), `configure_logging=True` |
| `ExitOptions` | `status_message=None`, `timeout_secs=30`, `exit_code=0`, `exit=True` |
| `CallOptions`, `StartOptions` | `token`, `build`, `max_total_charge_usd`, `restart_on_error`, `memory_mbytes`, `timeout` (`int` or `"inherit"`), `force_permission_level`, `webhooks`. All default to `None`. `build` is ignored on someone else's Actor, which runs the [User Build](https://scrape.ly/docs/publishing.md#user-build) |
| `AbortOptions` | `token=None`, `status_message=None`, `gracefully=None` |
| `MetamorphOptions` | `build=None` (ignored on someone else's Actor, which runs the [User Build](https://scrape.ly/docs/publishing.md#user-build)) |
| `RebootOptions` | `custom_after_sleep_millis=None` |
| `SetStatusMessageOptions` | `is_status_message_terminal=False`, `level="INFO"` |
| `OpenStorageOptions` | `force_cloud=False`, `config=None` |
| `RecordOptions` | `content_type=None`, `do_not_retry_timeouts=False`, `timeout_secs=None`. Exported for typing parity. `set_value()` takes `content_type` directly |
| `WebhookOptions` | `event_types`, `request_url`, `payload_template`, `idempotency_key`, `headers_template`, `description`, `ignore_ssl_errors=False`, `do_not_retry=False`, `should_interpolate_strings=False`, `is_apify_integration=False` |

## Result types

| Class | Fields |
| --- | --- |
| `ActorRun` | `id`, `actor_id`, `status`, `started_at`, `finished_at`, `duration_millis`, `build_id`, `build_number`, `default_dataset_id`, `default_key_value_store_id`, `default_request_queue_id`, `exit_code`, `status_message`, `input`, `output`, `usage_total_usd`, `usage` |
| `ChargeResult` | `chargeable_within_limit`, `charged_count`, `event_charge_limit_reached` |
| `ActorPricingInfoResult` | `is_pay_per_event`, `max_total_charge_usd`, `per_event_prices`, `pricing_model` |
| `ProxyInfo` | `url`, `scheme`, `hostname`, `port`, `username`, `password`, `session_id`, `proxy_tier`, `groups`, `country_code`, `subdivision_code` |
| `ApifyEnv` | See [Environment](https://scrape.ly/docs/sdk-python-environment.md#actorgetenv) |

`ActorRun` objects returned by `start()`, `call()` and `abort()` fill only the fields the endpoint returned. The others are `None`.

## Root exports

**Core:** `Actor`, `Configuration`, `set_cdp_url`, `BrowserConfiguration`

**Options and types:** `InitOptions`, `ExitOptions`, `CallOptions`, `StartOptions`, `AbortOptions`, `MetamorphOptions`, `RebootOptions`, `SetStatusMessageOptions`, `RecordOptions`, `OpenStorageOptions`, `WebhookOptions`, `ActorInput`, `ActorRun`, `ApifyEnv`, `ActorPermissionLevel`

**Storage:** `Dataset`, `KeyValueStore`, `RequestQueue`, `Request`, `DatasetItemsListPage`, `StorageClient`, `ApiStorageClient`, `ScrapelyStorageClient`, `SmartScrapelyStorageClient`, `FileSystemStorageClient`, `MemoryStorageClient`, `set_api_storage`

**Request loaders:** `ScrapelyRequestList`, `RequestLoader`, `RequestManager`, `RequestManagerTandem`, `SitemapRequestLoader`

**Events:** `Event`, `EventListener`, `EventManager` (alias of `ScrapelyEventManager`), `ScrapelyEventManager`, `CrawleeEventManager`, `LocalEventManager`, `ActorEventTypes`, `PersistStateEvent`, `SystemInfoEvent`, `MigratingEvent`, `AbortingEvent`, `ExitEvent`, `EventWithoutData`, `DeprecatedEvent`, `UnknownEvent`, `EventMessage`, `SystemInfoEventData`, `EventAbortingData`, `EventExitData`, `EventMigratingData`, `EventPersistStateData`, `EventSystemInfoData`

**Proxy:** `ProxyConfiguration`, `ProxyInfo`

**Charging:** `ChargingManager`, `ChargeResult`, `ChargeUncertainError`, `ChargeRejectedError`, `merge_charge_results`, `push_data_and_charge`, `create_charging_client`, `push_data_charging_context`, `USES_PUSH_DATA_INTERCEPTION`

**Pricing:** `PricingModel`, `ActorPricingInfo`, `ActorPricingInfoResult`, `ActorChargeEvent`, `PricingPerEvent`, `FreeActorPricingInfo`, `FlatPricePerMonthActorPricingInfo`, `PricePerDatasetItemActorPricingInfo`, `PayPerEventActorPricingInfo`

**Webhooks:** `Webhook`, `WebhookEventType`

**Errors:** `ScrapelyClientError`, `ScrapelyApiError`, `InvalidResponseBodyError`, `InvalidRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ServerError`, `raise_for_status`

Also importable from the root, though they aren't in `__all__`, are `APIFY_DEFAULT_DATASET_ITEM_EVENT` (`"apify-default-dataset-item"`), `SCRAPELY_DEFAULT_DATASET_ITEM_EVENT` (`"scrapely-default-dataset-item"`), `is_default_dataset_item_event`, `resolve_default_dataset_item_event_name` and `has_default_dataset_item_event_in_pricing`.

### Submodules

| Module | Contents |
| --- | --- |
| `scrapely.storage` | `ApiClient`, `ApiClientError`, `set_storage_client`, `persist_autosaved_values` and other storage internals |
| `scrapely.storages` | `Dataset`, `KeyValueStore`, `RequestQueue` |
| `scrapely.storage_clients` | Storage client classes, including the `ApifyStorageClient` and `SmartApifyStorageClient` aliases |
| `scrapely.request_loaders` | `ScrapelyRequestList` |
| `scrapely.log` | The `scrapely` logger and `ActorLogFormatter` |

In Scrape.ly images, `import apify` resolves to a shim that re-exports `scrapely`.

## Differences from the JavaScript SDK

| Area | JavaScript | Python |
| --- | --- | --- |
| Options | Object literals | Dataclass instances passed positionally (`exit()`/`fail()` also take keywords) |
| `useState` / `use_state` | `useState(name, defaultValue)` | `use_state(default_value, key)` |
| `setValue` / `set_value` | `RecordOptions` object | `content_type` argument |
| Entrypoint | `Actor.main(fn)` | `async with Actor:` or `Actor.main(fn)` |
| Standby | Built-in helper | `Actor.is_standby()` plus your own server |
| Crawlers | Re-exported from the SDK | Imported from `crawlee.crawlers` |

## What's next

- [Lifecycle](https://scrape.ly/docs/sdk-python-lifecycle.md) shows these methods in context.
- [Errors & deployment](https://scrape.ly/docs/sdk-python-deploy.md) covers failures and packaging.
- The [JavaScript SDK reference](https://scrape.ly/docs/sdk-node-reference.md) is the Node.js equivalent.

---

- Previous: [Errors & deployment](https://scrape.ly/docs/sdk-python-deploy.md)
- Next: [CLI reference](https://scrape.ly/docs/cli.md)
- All docs: [Docs index](https://scrape.ly/docs.md), [llms.txt](https://scrape.ly/llms.txt)