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.
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.
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.
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.
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 |
AbortOptions | token=None, status_message=None, gracefully=None |
MetamorphOptions | build=None (ignored on someone else's Actor, which runs the 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 |
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 shows these methods in context.
- Errors & deployment covers failures and packaging.
- The JavaScript SDK reference is the Node.js equivalent.
