JavaScript SDK

API reference

Every Actor member and root export of the JavaScript SDK.

A complete listing of the Actor API and the root exports of scrapely. For explanations and examples, follow the topic pages linked from the SDK overview.

Lifecycle

Member	Signature	Notes
`init`	`init(options?: InitOptions): Promise<void>`	Connects storage, events, and charging
`main`	`main<T>(userFunc: UserFunc<T>, options?: MainOptions): Promise<T>`	`init`, run, shut down, `process.exit()`
`exit`	`exit(messageOrOptions?: string \| ExitOptions, options?: ExitOptions): Promise<void>`	Exit code `0` by default
`fail`	`fail(messageOrOptions?: string \| ExitOptions, options?: ExitOptions): Promise<void>`	Exit code `1` by default
`reboot`	`reboot(options?: RebootOptions): Promise<void>`	Restarts the container, keeps the run; doesn't return
`abort`	`abort(runId?: string, options?: AbortOptions): Promise<ActorRun>`	Aborts this run or another
`metamorph`	`metamorph(targetActorId: string, input?: Record<string, any> \| string \| Buffer, options?: MetamorphOptions): Promise<void>`	Hands the run to another Actor; doesn't return

Type	Fields
`InitOptions`	`configuration?`, `storage?: ApiStorageConfig \| StorageClient`, `gracefulShutdown?` (`true`), `gracefulShutdownDelayMillis?` (`0`)
`ExitOptions`	`statusMessage?`, `timeoutSecs?` (`30`), `exitCode?`, `exit?` (`true`)
`MainOptions`	`ExitOptions & InitOptions`; `exit` is ignored
`AbortOptions`	`gracefully?`, `statusMessage?`, `token?`
`MetamorphOptions`	`build?` (ignored on someone else's Actor, which runs the User Build), `contentType?` (not sent)
`RebootOptions`	No public fields
`UserFunc<T>`	`() => T \| Promise<T>`

Input and output

Member	Signature
`getInput`	`getInput<T = ActorInput>(): Promise<T \| null>`
`getInputOrThrow`	`getInputOrThrow<T = ActorInput>(): Promise<T>`
`input`	`static get input(): Record<string, any> \| undefined`
`pushData`	`pushData<Data extends Record<string, any>>(item: Data \| Data[]): Promise<void>`
`pushData`	`pushData<Data extends Record<string, any>>(item: Data \| Data[], eventName: string): Promise<ChargeResult>`
`getValue`	`getValue<T>(key: string): Promise<T \| null>`
`setValue`	`setValue<T>(key: string, value: T \| null, options?: RecordOptions): Promise<void>`

ActorInput is Record<string, any> | string | Buffer. RecordOptions has contentType?, doNotRetryTimeouts?, and timeoutSecs?. Passing null to setValue() deletes the record. On pay-per-event Actors with a default dataset item event, pushData(item) also returns a ChargeResult.

Storages

Member	Signature
`openDataset`	`openDataset<T>(nameOrIdOrOptions?: string \| null \| StorageIdentifier, openOptions?: OpenStorageOptions): Promise<Dataset<T>>`
`openKeyValueStore`	`openKeyValueStore(nameOrIdOrOptions?: string \| null \| StorageIdentifier, openOptions?: OpenStorageOptions): Promise<KeyValueStore>`
`openRequestQueue`	`openRequestQueue(nameOrIdOrOptions?: string \| null \| StorageIdentifier, openOptions?: OpenStorageOptions): Promise<RequestQueue>`

StorageIdentifier is { id }, { name }, or { alias }. OpenStorageOptions has config? and forceCloud?. With no argument, each method opens the run's default storage.

Events and state

Member	Signature
`on`	`on(event: EventTypeName \| 'cpuInfo', listener: (...args: any[]) => void): void`
`off`	`off(event: EventTypeName \| 'cpuInfo', listener?: (...args: any[]) => void): void`
`events`	`static get events(): EventEmitter`
`useState`	`useState<State>(nameOrInitialState?: string \| State, defaultValue?: State, options?: { keyValueStoreName?: string; config?: Configuration }): Promise<State>`
`setStatusMessage`	`setStatusMessage(message: string, options?: SetStatusMessageOptions): Promise<ActorRun>`

SetStatusMessageOptions has isStatusMessageTerminal? and level?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR'. off() with no listener removes every listener for that event.

Orchestration and webhooks

Member	Signature
`call`	`call(actorId: string, input?: unknown, options?: CallOptions): Promise<ActorRun>`
`callTask`	`callTask(taskId: string, input?: Record<string, any>, options?: CallTaskOptions): Promise<ActorRun>`
`start`	`start(actorId: string, input?: Record<string, any>, options?: StartOptions): Promise<ActorRun>`
`addWebhook`	`addWebhook(options: WebhookOptions): Promise<Webhook \| undefined>`

CallOptions, CallTaskOptions, and StartOptions are the scrapely-client call and start options plus token? and timeout?: number | 'inherit'. WebhookOptions has eventTypes, requestUrl, and optional payloadTemplate, headersTemplate, description, idempotencyKey, ignoreSslErrors, doNotRetry, shouldInterpolateStrings, and isApifyIntegration.

Charging

Member	Signature
`charge`	`charge(options: ChargeOptions \| string, count?: number): Promise<ChargeResult>`
`getChargingManager`	`getChargingManager(): ChargingManager`

Type	Fields
`ChargeOptions`	`eventName: string`, `count?: number` (`1`)
`ChargeResult`	`eventChargeLimitReached: boolean`, `chargedCount: number`, `chargeableWithinLimit: Record<string, number>`
`ActorPricingInfo`	`pricingModel?`, `isPayPerEvent`, `maxTotalChargeUsd`, `perEventPrices: Record<string, number>`

ChargingManager has getPricingInfo(), getChargedEventCount(eventName), getMaxTotalChargeUsd(), calculateMaxEventChargeCountWithinLimit(eventName), calculatePushDataLimits({ eventName, isDefaultDataset, items }) (returns { eventsToCharge, limitedItems }), and charge(options). See Charging.

Proxy and browser

Member	Signature
`createProxyConfiguration`	`createProxyConfiguration(options?: CreateProxyConfigurationOptions): Promise<ProxyConfiguration \| undefined>`
`createBrowserConfiguration`	`createBrowserConfiguration(options?: BrowserConfigurationOptions): Promise<BrowserConfiguration>`

CreateProxyConfigurationOptions adds useScrapelyProxy? and checkAccess? (true) to ProxyConfigurationOptions. That type adds groups?, countryCode?, subdivisionCode?, password?, tieredProxyConfig?, and the scrapelyProxyGroups? / scrapelyProxyCountry? / scrapelyProxySubdivision? input-field options to Crawlee's proxy options (proxyUrls, newUrlFunction, tieredProxyUrls).

BrowserConfigurationOptions has countryCode?, state?, city?, os?: 'windows' | 'macos' | 'android', timezone?, language?, adblock?, solveCloudflare?, and the browserCountry? / browserState? / browserCity? aliases. See Proxy & events.

Environment and clients

Member	Signature
`isAtHome`	`isAtHome(): boolean`
`isStandby`	`isStandby(): boolean`
`getEnv`	`getEnv(): ApifyEnv`
`getenv`	`static getenv(key: string): string \| undefined`
`getRemainingTime`	`static getRemainingTime(): number \| undefined`
`config`	`Configuration` (static getter and instance property)
`apifyClient`	`get apifyClient(): ApifyClient`
`newClient`	`newClient(options?: { token?: string; baseUrl?: string }): ApifyClient`
`getDefaultInstance`	`static getDefaultInstance(): Actor`
`utils`	`static readonly utils: { enqueueLinks }`

getRemainingTime() returns milliseconds until the run times out, or undefined when there's no timeout. ApifyClient is the scrapely-client client; see JavaScript client.

Run metadata

All of these are static getters.

Getter	Type
`fullName`	`string \| undefined`
`taskId`	`string \| undefined`
`buildId`	`string \| undefined`
`buildNumber`	`string \| undefined`
`buildTags`	`string[]`
`startedAt`	`string \| undefined`
`timeoutAt`	`string \| undefined`
`token`	`string \| undefined`
`userId`	`string \| undefined`
`isPaying`	`boolean`
`apiPublicBaseUrl`	`string \| undefined`

There are no web server or standby getters. Use Actor.config.get('containerPort'), Actor.config.get('containerUrl'), and Actor.config.get('standbyUrl'); see Standby mode.

Static-only members

events, input, getenv(), getRemainingTime(), getDefaultInstance(), utils, and the run metadata getters exist only as statics. Everything else, including getEnv(), isAtHome(), and isStandby(), also exists on instances (new Actor() or Actor.getDefaultInstance()).

Root exports

Actor

Actor, ACTOR_PERMISSION_LEVEL (NONE, RUN, WRITE, ADMIN), EXIT_CODES (SUCCESS: 0, ERROR_USER_FUNCTION_THREW: 91, ERROR_UNKNOWN: 92)

Types: ActorInput, InitOptions, MainOptions, ExitOptions, RebootOptions, AbortOptions, MetamorphOptions, RecordOptions, OpenStorageOptions, CallOptions, CallTaskOptions, StartOptions, SetStatusMessageOptions, WebhookOptions, ApifyEnv, UserFunc, Token, Timeout, StorageAlias, StorageId, StorageName, StorageIdentifier, StorageIdentifierWithoutAlias

Configuration and events

Configuration, ConfigurationOptions (type), PlatformEventManager

API client (from scrapely-client)

ApifyClient, ApifyClientOptions (type), ActorRun (type)

Charging

ChargingManager, ChargeUncertainError, ChargeRejectedError, DEFAULT_DATASET_ITEM_EVENT, APIFY_DEFAULT_DATASET_ITEM_EVENT, SCRAPELY_DEFAULT_DATASET_ITEM_EVENT, hasDefaultDatasetItemEventInPricing, isDefaultDatasetItemEvent, resolveDefaultDatasetItemEventName, mergeChargeResults, pushDataAndCharge, ChargeOptions, ChargeResult, ActorPricingInfo (types)

Lower-level charging and storage internals are exported too: createChargingClient, pushDataChargingContext, USES_PUSH_DATA_INTERCEPTION, PpeAwarePushDataContext, BillingTracker, BillingClient, ApiStorageClientFactory, ApiStorageConfig. Most Actors don't need them.

Proxy

ProxyConfiguration, createProxyConfiguration, isPlatformProxySentinel, validateProxySessionId, getPlatformProxyEnv, and the types ProxyConfigurationOptions, CreateProxyConfigurationOptions, PlatformProxyEnv, ProxyInfo, ProxyConfigurationFunction

Browser

BrowserConfiguration, createBrowserConfiguration, BrowserConfigurationOptions (type), setCdpUrl

Storage and requests

Dataset, KeyValueStore, RequestQueue, ScrapelyRequestList, RequestListSource (type), KeyConsumer (type), and the Crawlee types KeyValueStoreIteratorOptions, KeyValueStoreOptions, DatasetConsumer, DatasetContent, DatasetDataOptions, DatasetIteratorOptions, DatasetMapper, DatasetOptions, DatasetReducer, QueueOperationInfo, RequestQueueOperationOptions, RequestQueueOptions

Crawlee re-exports

Crawlers (BasicCrawler, BrowserCrawler, CheerioCrawler, HttpCrawler, JSDOMCrawler, LinkeDOMCrawler, PlaywrightCrawler, PuppeteerCrawler), browser utilities (playwrightUtils, puppeteerUtils), and logging (log, Log, LogLevel, Logger, LoggerJson, LoggerText, LoggerOptions)

Helpers

utils, enqueueLinks, EnqueueLinksOptions (type)

Request and RequestList aren't re-exported; import them from crawlee when you need them.

Import side effects

Importing the package does two things:

It copies ACTOR_LOG_LEVEL and ACTOR_LOG_FORMAT to APIFY_LOG_LEVEL and APIFY_LOG_FORMAT when those aren't set. The log library reads them once when it loads, so import scrapely before crawlee or any @crawlee/* package.
It patches Crawlee's browser pool and the Playwright and Puppeteer launchers to connect to the Scrape.ly browser when the Actor's build has it turned on (SCRAPELY_BROWSER_PATCH isn't 0). This also covers Crawlee copies that were loaded earlier.

What's next

Lifecycle: the methods above in context
JavaScript client: the API client behind Actor.apifyClient
Python SDK reference