---
title: "API reference · Scrape.ly Docs"
description: "Every Actor member and root export of the JavaScript SDK."
url: https://scrape.ly/docs/sdk-node-reference
markdown: https://scrape.ly/docs/sdk-node-reference.md
---

# 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](https://scrape.ly/docs/sdk-node.md).

## 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](https://scrape.ly/docs/publishing.md#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](https://scrape.ly/docs/sdk-node-actors.md).

## 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](https://scrape.ly/docs/sdk-node-proxy-events.md).

## 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](https://scrape.ly/docs/client-js.md).

## 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](https://scrape.ly/docs/sdk-node-standby.md).

## 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](https://scrape.ly/docs/browser.md) 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](https://scrape.ly/docs/sdk-node-lifecycle.md): the methods above in context
- [JavaScript client](https://scrape.ly/docs/client-js.md): the API client behind `Actor.apifyClient`
- [Python SDK reference](https://scrape.ly/docs/sdk-python-reference.md)

---

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