Apify SDK

https://github.com/apify/apify-sdk-js
Admin
Apify SDK is a scalable web crawling and scraping library for JavaScript/Node.js that enables...
Tokens:70,821
Snippets:408
Trust Score:9.9
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### getValue and setValue usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

JavaScript example setting a value and then getting it from the default key-value store.

```javascript
await Actor.setValue('OUTPUT', { ok: true });
const out = await Actor.getValue('OUTPUT');
```

--------------------------------

### Configuration usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/configuration.md

Shows how to import and use the Configuration class and Actor constructor. Demonstrates getting the global configuration, creating a per-instance config with a token, and creating a custom configuration with an API base URL override. Note that environment variables still take precedence over explicit overrides.

```javascript
import { Actor, Configuration } from 'apify';

// Global singleton (respects env vars)
const config = Configuration.getGlobalConfiguration();
console.log(config.headless, config.persistStateIntervalMillis, config.token);

// Per-instance config via the Actor constructor
const sdk = new Actor({ token: '123' });
console.log(sdk.configuration.token); // '123'

// Explicit overrides; env vars still win
const custom = new Configuration({ apiBaseUrl: 'http://localhost:8000' });
```

--------------------------------

### createProxyConfiguration usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

JavaScript example showing how to create a proxy configuration with a group and country code.

```javascript
const proxyConfiguration = await Actor.createProxyConfiguration({ groups: ['GROUP1'], countryCode: 'US' });
```

--------------------------------

### start

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Like `call`, but returns immediately after the run starts (no `waitForFinish`).

```APIDOC
## start

### Description
Like `call`, but returns immediately after the run starts (no `waitForFinish`).

### Method
async start(actorId: string, input?: ActorInput, options: StartOptions = {}): Promise<ClientActorRun>
static async start(actorId: string, input?: Dictionary, options: StartOptions = {}): Promise<ClientActorRun>

### Parameters
- **actorId** (string) - Required - The Actor ID, `username/actor-name`, or `userId/actor-name`.
- **input** (ActorInput or Dictionary) - Optional - The input for the Actor run.
- **options** (StartOptions) - Optional - Options for starting the run.

### Response
Returns a `ClientActorRun` object.
```

--------------------------------

### New preLaunchHook example

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Recreates the same functionality as launchPuppeteerFunction using a preLaunchHook in browserPoolOptions.

```javascript
const maybeLaunchChrome = (pageId, launchContext) => {
    if (someVariable === 'chrome') {
        launchContext.useChrome = true;
    }
};

const crawler = new Apify.PuppeteerCrawler({
    browserPoolOptions: {
        preLaunchHooks: [maybeLaunchChrome],
    },
    // ...
});
```

--------------------------------

### Actor.main usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Example of using Actor.main with an async user function that gets input and logs it. Terminates the process when done.

```javascript
await Actor.main(async () => {
    const input = await Actor.getInput();
    console.log('Processing', input);
});
```

--------------------------------

### StartOptions

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Options for starting an Actor, extending ActorStartOptions with token and timeout.

```APIDOC
## StartOptions

### Description
Options for starting an Actor, extending ActorStartOptions with token and timeout.

### Properties
Inherits from ActorStartOptions (excluding waitForFinish and runTimeoutSecs), Token, and Timeout.
```

--------------------------------

### Install SDK v1 with Puppeteer

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Run this command to install Apify SDK v1 with Puppeteer support, matching previous SDK versions.

```bash
npm install apify puppeteer
```

--------------------------------

### Install SDK v1 with Playwright

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Run this command to install Apify SDK v1 with Playwright support. Note that Playwright is not supported on the Apify Platform without a compatible Docker image.

```bash
npm install apify playwright
```

--------------------------------

### Actor.init usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Example of calling Actor.init with gracefulShutdown enabled.

```javascript
await Actor.init({ gracefulShutdown: true });
```

--------------------------------

### Run tests with npm run test

Source: https://github.com/apify/apify-sdk-js/blob/master/CONTRIBUTING.md

Run the test suite before starting work to ensure all tests pass and the setup is correct. Also re-run after incorporating review feedback.

```sh
npm run test

```

--------------------------------

### Old launchPuppeteerFunction example

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows the old way of customizing browser launch with launchPuppeteerFunction, which required manual handling of options.

```javascript
const launchPuppeteerFunction = async (launchPuppeteerOptions) => {
    if (someVariable === 'chrome') {
        launchPuppeteerOptions.useChrome = true;
    }
    return Apify.launchPuppeteer(launchPuppeteerOptions);
};

const crawler = new Apify.PuppeteerCrawler({
    launchPuppeteerFunction,
    // ...
});
```

--------------------------------

### addWebhook usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

JavaScript example creating an ad-hoc webhook for the current run. Uses eventTypes and requestUrl; idempotencyKey is set to the current run ID.

```javascript
const webhook = await Actor.addWebhook({
    eventTypes: ['ACTOR.RUN.SUCCEEDED'],
    requestUrl: 'https://example.com/hook',
    idempotencyKey: Actor.getEnv().actorRunId,
});
```

--------------------------------

### pushData usage examples

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

JavaScript examples for pushing data to the default dataset, with and without an event name. The second example checks the charge result to see if the push was cut short.

```javascript
await Actor.pushData({ url: 'https://example.com', title: 'Example' });

const result = await Actor.pushData(dataItems, 'my-scrape-item');
if (result.chargedCount < dataItems.length) { /* budget cut the push short */ }
```

--------------------------------

### Install Apify SDK with npm

Source: https://github.com/apify/apify-sdk-js/blob/master/README.md

Install the Apify SDK package in a Node.js project. Requires Node.js 16 or later.

```bash
npm install apify
```

--------------------------------

### Initialize ProxyConfiguration with groups

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

JavaScript example showing how to create a ProxyConfiguration with a proxy group and call initialize. Prefer Actor.createProxyConfiguration() as it calls initialize() for you.

```javascript
// Prefer Actor.createProxyConfiguration() — it calls initialize() for you
const proxy = new ProxyConfiguration({ groups: ['BUYPROXIES94952'] });
const ok = await proxy.initialize({ checkAccess: true });
```

--------------------------------

### ChargingManager.charge usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/charging.md

Example of charging for a 'crawl-page' event and checking if the budget is exhausted.

```javascript
const result = await Actor.charge({ eventName: 'crawl-page', count: 1 });
if (result.chargedCount === 0) {
    console.log('Budget exhausted; stopping work.');
}
```

--------------------------------

### Actor.on usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Example of registering a listener for the persistState event, which is triggered periodically and on migration.

```javascript
Actor.on('persistState', ({ isMigrating }) => saveState());
```

--------------------------------

### New preNavigationHooks and postNavigationHooks example

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Replaces gotoFunction with preNavigationHooks and postNavigationHooks. preNavigationHooks receive crawlingContext and gotoOptions; postNavigationHooks receive only crawlingContext.

```javascript
const preNavigationHooks = [async ({ page }) => makePageStealthy(page)];

const postNavigationHooks = [
    async ({ page }) =>
        page.evaluate(() => {
            window.foo = 'bar';
        }),
];

const crawler = new Apify.PuppeteerCrawler({
    preNavigationHooks,
    postNavigationHooks,
    // ...
});
```

--------------------------------

### New launchContext example

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Uses the new launchContext object to explicitly define launchOptions. launchPuppeteerOptions were removed.

```javascript
const crawler = new Apify.PuppeteerCrawler({
    launchContext: {
        useChrome: true, // Apify option
        launchOptions: {
            headless: false, // Puppeteer option
        },
    },
});
```

--------------------------------

### Get a new proxy URL

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

JavaScript example showing how to get a new proxy URL from a ProxyConfiguration instance. The output shows the format for Apify Proxy: http://groups-XXX,session-xxxx,your-password@proxy.apify.com:8000.

```javascript
const url = await proxyConfiguration.newUrl();
console.log(url); // http://groups-XXX,session-xxxx,your-password@proxy.apify.com:8000
```

--------------------------------

### Actor.start method signatures

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

TypeScript overloads for the instance and static start methods. Starts an Actor run without waiting for it to finish.

```typescript
async start(actorId: string, input?: ActorInput, options: StartOptions = {}): Promise<ClientActorRun>
static async start(actorId: string, input?: Dictionary, options: StartOptions = {}): Promise<ClientActorRun>
```

--------------------------------

### Usage example with deep import

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/input-schemas.md

Shows how to use the internal functions via a deep import. It reads the schema and, if it's an object, infers defaults and logs them.

```javascript
import { readInputSchema, getDefaultsFromInputSchema } from 'apify/src/input-schemas.js'; // deep import (internal)

const schema = readInputSchema();
if (schema && typeof schema === 'object') {
    const defaults = getDefaultsFromInputSchema(schema);
    console.log(defaults);
}
```

--------------------------------

### getInput usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

JavaScript example showing how to call Actor.getInput() and handle the NOT_FOUND error. The input is not cached.

```javascript
let input = {};
try {
    input = await Actor.getInput();
} catch (error) {
    if (!(error instanceof ActorInputError) || error.code !== 'NOT_FOUND') throw error;
}
```

--------------------------------

### Old launchPuppeteerOptions example

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows the old way of merging Apify options with Puppeteer launchOptions, which caused confusion.

```javascript
const launchPuppeteerOptions = {
    useChrome: true, // Apify option
    headless: false, // Puppeteer option
};
```

--------------------------------

### Actor.call usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Calls the 'apify/hello-world' Actor with input and logs the run status.

```javascript
const run = await Actor.call('apify/hello-world', { myInput: 123 });
console.log(run.status);
```

--------------------------------

### Old gotoFunction example

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows the complexity of overriding gotoFunction, requiring manual handling of pre-processing, gotoExtended, post-processing, and returning the response.

```javascript
const gotoFunction = async ({ request, page }) => {
    // pre-processing
    await makePageStealthy(page);

    // Have to remember how to do this:
    const response = gotoExtended(page, request, {
        /* have to remember the defaults */
    });

    // post-processing
    await page.evaluate(() => {
        window.foo = 'bar';
    });

    // Must not forget!
    return response;
};

const crawler = new Apify.PuppeteerCrawler({
    gotoFunction,
    // ...
});
```

--------------------------------

### Actor.exit usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Example of calling Actor.exit with a status message and exit code 0.

```javascript
await Actor.exit('All done', { exitCode: 0 });
```

--------------------------------

### Using ApifyStorageBackend with ApifyClient and Dataset

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

Shows how to open a dataset with a custom storage backend. The ApifyClient is created with a token, then Dataset.open is called with the dataset ID and the storage backend instance. The resulting dataset can be used to get data.

```typescript
import { ApifyClient, ApifyStorageBackend, Dataset } from 'apify';

const client = new ApifyClient({ token });
const dataset = await Dataset.open(datasetId, { storageBackend: new ApifyStorageBackend(client) });
const { items } = await dataset.getData();
```

--------------------------------

### Actor.charge usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Charges for an event and logs the charged count and whether more charges are allowed within the limit.

```javascript
const result = await Actor.charge({ eventName: 'my-event', count: 10 });
console.log(result.chargedCount, result.chargeableWithinLimit);
```

--------------------------------

### Proxy Configuration and Info Interfaces

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/types.md

Defines ProxyConfigurationOptions and ProxyInfo interfaces for proxy setup. ProxyConfigurationOptions extends CoreProxyConfigurationOptions with fields like password, groups, countryCode, and checkAccess (default true). ProxyInfo extends CoreProxyInfo with password and optional group/country fields. These are used with Actor.createProxyConfiguration() and new ProxyConfiguration().

```typescript
export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions {
    password?: string;
    groups?: string[];
    countryCode?: string;
    subdivisionCode?: string;
    apifyProxyGroups?: string[];
    apifyProxyCountry?: string;
    apifyProxySubdivision?: string;
    checkAccess?: boolean;      // default true
}

export interface ProxyInfo extends CoreProxyInfo {
    groups?: string[];
    countryCode?: string;
    subdivisionCode?: string;
    password: string;
}
```

--------------------------------

### createProxyConfiguration

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Builds and initializes a ProxyConfiguration. Returns undefined for the Input-UI compatibility case with no proxyUrls.

```APIDOC
## `createProxyConfiguration`

### Description
Builds and initializes a [`ProxyConfiguration`](./proxy-configuration.md). Returns `undefined` for the Input-UI compatibility case `{ useApifyProxy: false }` with no `proxyUrls`. Initialization verifies access via the proxy status endpoint unless `checkAccess: false`.

### Method
`async createProxyConfiguration(proxyConfigurationOptions: ProxyConfigurationOptions & { useApifyProxy?: boolean } = {}): Promise<ProxyConfiguration | undefined>`

### Parameters
#### Request Body
- `proxyConfigurationOptions` (ProxyConfigurationOptions & { useApifyProxy?: boolean }) - Required - Options for the proxy configuration. See `ProxyConfigurationOptions` for details.

### Request Example
```js
const proxyConfiguration = await Actor.createProxyConfiguration({ groups: ['GROUP1'], countryCode: 'US' });
```

### Response
Returns a promise that resolves to a `ProxyConfiguration` instance or `undefined`.

```

--------------------------------

### Get page ID from browserPool

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows how to get the page ID using browserPool.getPageId, which is equal to crawlingContext.id.

```javascript
const pageId = browserPool.getPageId;
```

--------------------------------

### init

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Initializes the Actor: sets global crawlee configuration, registers storage backend, initializes event manager, and sets up graceful shutdown handlers.

```APIDOC
## init

### Description
Initializes the Actor: sets the global crawlee configuration, registers the storage backend (a `SmartApifyStorageBackend` unless a custom `storage` is given), initializes the event manager, registers graceful-shutdown handlers for `aborting`/`migrating` events (when `gracefulShutdown !== false`), forwards crawlee `statusMessage` events, purges default storages, and initializes the `ChargingManager`.

Throws `Error` if called after a warning about a missing init call was emitted ("Actor.init() was called after a method that would access a storage client was used..."), or when a storage backend was already registered with crawlee's service locator. A second call is a no-op (`log.debug`).

### Method
`init`

### Signature
```ts
async init(options: InitOptions = {}): Promise<void>
static async init(options: InitOptions = {}): Promise<void>
```

### Parameters
- **options** (`InitOptions`) - Optional - Initialization options (default `{}`)

### Example
```js
await Actor.init({ gracefulShutdown: true });
```
```

--------------------------------

### Predefined preLaunchHooks array

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows how to compose multiple preLaunchHooks for pre-defined browser behavior.

```javascript
const preLaunchHooks = [
    maybeLaunchChrome,
    useHeadfulIfNeeded,
    injectNewFingerprint,
];
```

--------------------------------

### init

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/charging.md

Initializes the ChargingManager by loading pricing info and seeding charging state.

```APIDOC
## init

### Description
Loads pricing info and charged-event counts — from the platform-injected `actorPricingInfo`/`chargedEventCounts` config fields when present, else from the run via `apifyClient.run(actorRunId).get()` (on the platform) — then seeds the charging state. When `useChargingLogDataset` is set, creates (locally: purges then opens `'charging_log'`; on platform: `getOrCreate()`s a dataset and stores its id in the default key-value store under `CHARGING_LOG_DATASET_ID`) the charge-log dataset. `testPayPerEvent` forces `pricingModel = 'PAY_PER_EVENT'`.

### Method
`async init(): Promise<void>`

### Errors
Throws (all plain `Error`):
- `'Using the ACTOR_USE_CHARGING_LOG_DATASET environment variable is only supported in a local development environment'` — when `useChargingLogDataset` is set on the platform.
- `'Using the ACTOR_TEST_PAY_PER_EVENT environment variable is only supported in a local development environment'` — when `testPayPerEvent` is set on the platform.
- `'Actor run ID not found even though the Actor is running on Apify'` — platform run without `actorRunId`.
- `'Actor run not found'` — platform run whose `GET /v2/actor-runs/{id}` returns `undefined`.

### Notes
Called automatically by `Actor.init()`.
```

--------------------------------

### InitOptions

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Options for initializing the Actor, including custom storage backend, request queue access mode, and graceful shutdown behavior.

```APIDOC
## InitOptions

### Description
Options for initializing the Actor, including custom storage backend, request queue access mode, and graceful shutdown behavior.

### Properties
- **storage** (StorageBackend) - Optional - Custom storage backend (items pushed to the default dataset are then not charged under pay-per-event).
- **requestQueueAccess** (RequestQueueAccessMode) - Optional - 'single' | 'shared'; default 'single'.
- **gracefulShutdown** (boolean) - Optional - Default true; calls Actor.exit() on `aborting`, Actor.reboot() on `migrating`.
- **gracefulShutdownDelayMillis** (number) - Optional - Default 0.
```

--------------------------------

### init()

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/platform-event-manager.md

Initializes the base event manager and, when configured, opens a WebSocket to the Actor-events stream. Handles incoming messages and emits events accordingly.

```APIDOC
## init()

### Description
Initializes the base event manager and, when `configuration.actorEventsWsUrl` is set, opens a WebSocket to the Actor-events stream. Locally (no URL) it logs a warning. A second call is a no-op.

### Method
async init()

### Signature
```ts
override async init()
```

### Behavior
- Opens a WebSocket to `configuration.actorEventsWsUrl` if set.
- Parses incoming JSON messages `{ name, data }` and emits `name` with `data` on the internal emitter.
- On `ACTOR_EVENT_NAMES.MIGRATING`, stops the persist-state interval and emits `persistState` with `{ isMigrating: true }`.
- Unparseable messages are logged via `log.exception`.
- Websocket errors are logged; the 'WebSocket was closed before the connection was established' error is silently ignored.
- On close, the socket reference is cleared.
```

--------------------------------

### Actor.useState usage example

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Creates a state object with a default value and increments a property; changes are auto-persisted.

```javascript
const state = await Actor.useState('my-state', { processed: 0 });
state.processed += 1; // auto-persisted
```

--------------------------------

### SmartApifyStorageBackend options and class definition

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

Defines the options interface and class for SmartApifyStorageBackend. The constructor takes cloudStorageBackend, localStorageBackend, and configuration. The class implements StorageBackend and routes storages to cloud or local based on configuration.isAtHome.

```typescript
export interface SmartApifyStorageBackendOptions {
    cloudStorageBackend: StorageBackend;
    localStorageBackend: StorageBackend;
    configuration: Configuration;
}

export class SmartApifyStorageBackend implements StorageBackend {
    constructor(options: SmartApifyStorageBackendOptions)
}
```

--------------------------------

### main

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Runs the Actor lifecycle: initializes, executes the user function, and exits. Terminates the process when done.

```APIDOC
## main

### Description
Runs `init(options)`, then `userFunc()`, then `exit(options)`. If the user function throws, the error is logged with `log.exception()` and `exit({ exitCode: EXIT_CODES.ERROR_USER_FUNCTION_THREW })` is called. Throws `Error` when the first parameter is not a function. **Terminates the process when done** — avoid in long-running servers.

### Method
`main`

### Signature
```ts
async main<T>(userFunc: UserFunc, options?: MainOptions): Promise<T>
static async main<T>(userFunc: UserFunc<T>, options?: MainOptions): Promise<T>
```

### Parameters
- **userFunc** (`UserFunc`) - Required - User function, sync or async, called with no arguments
- **options** (`MainOptions`) - Optional - Passed to `init()` and `exit()`

### Example
```js
await Actor.main(async () => {
    const input = await Actor.getInput();
    console.log('Processing', input);
});
```
```

--------------------------------

### Using createTransformRequestFunction with enqueueLinks

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/enqueue-links-filters.md

Example of using the transformation function within an enqueueLinks call to filter requests based on input globs.

```ts
import { Actor, createTransformRequestFunction } from 'apify';

const input = await Actor.getInput(); // { globs: ['https://example.com/**'] }

await enqueueLinks({
    transformRequestFunction: createTransformRequestFunction({ globs: input.globs }),
});
```

--------------------------------

### newClient

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Constructs an ApifyClient from the current configuration, appending SDK and Crawlee user-agent suffixes. Useful for acting as a different Apify user.

```APIDOC
## newClient

### Description
Constructs an ApifyClient from the current configuration, appending SDK and Crawlee user-agent suffixes. Useful for acting as a different Apify user.

### Method
newClient

### Signature
```ts
newClient(options: ApifyClientOptions = {}): ApifyClient
static newClient(options: ApifyClientOptions = {}): ApifyClient
```

### Parameters
- **options** (ApifyClientOptions) - Optional - Options that override the configuration. Defaults to `{}`.

### Response
- **ApifyClient** - A new ApifyClient instance.
```

--------------------------------

### Catch ArgumentValidationError from openDataset

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/errors.md

Catching ArgumentValidationError thrown by parseArgument() when a validated argument has a wrong type or unknown keys. The example shows a wrong type for the forceCloud option.

```javascript
try {
    await Actor.openDataset('name', { forceCloud: 'yes' }); // wrong type
} catch (error) {
    if (error instanceof ArgumentValidationError) console.error(error.message);
}
```

--------------------------------

### Configure Apify SDK with Configuration and Actor

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/configuration.md

Shows three ways to configure the Apify SDK: using the global singleton, passing field-level overrides to the Actor constructor, and providing a pre-built Configuration instance. Env vars take precedence over field-level overrides, but a pre-built configuration wins over field-level overrides.

```javascript
import { Actor, Configuration } from 'apify';

// 1) Global singleton — respects env vars
const config = Configuration.getGlobalConfiguration();
console.log(config.token, config.headless, config.persistStateIntervalMillis);

// 2) Actor with overrides (env vars take precedence)
const sdk = new Actor({ token: '123', apiBaseUrl: 'http://localhost:8000' });

// 3) Pre-built configuration wins over field-level overrides
const actor = new Actor({ configuration: new Configuration({ inputKey: 'MY_INPUT' }) });
```

--------------------------------

### preLaunchHook with crawlingContext access

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Demonstrates how preLaunchHooks can access the crawlingContext of the request that triggered the launch via crawler.crawlingContexts.

```javascript
const preLaunchHooks = [
    async function maybeLaunchChrome(pageId, launchContext) {
        const { request } = crawler.crawlingContexts.get(pageId);
        if (request.userData.useHeadful === true) {
            launchContext.launchOptions.headless = false;
        }
    },
];
```

--------------------------------

### DEFAULT_DATASET_ITEM_EVENT constant

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/charging.md

The synthetic per-item event the platform bills for items stored in the run's default dataset. Charged automatically by ChargingDatasetBackend for every item pushed; Actor.pushData(item, eventName) rejects event names starting with 'apify-' ("Cannot charge for synthetic event ... manually"). Not exported from the package root.

```typescript
export const DEFAULT_DATASET_ITEM_EVENT = 'apify-default-dataset-item';
```

--------------------------------

### Create Custom Proxy Configuration with Round-Robin Rotation

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

Creates a proxy configuration using custom proxy URLs that are rotated round-robin. Cannot be combined with Apify Proxy options.

```javascript
// Custom proxies, rotated round-robin (cannot be combined with Apify options)
const custom = await Actor.createProxyConfiguration({
    proxyUrls: ['http://user:pass@127.0.0.1:8080'],
});
```

--------------------------------

### configuration (static getter)

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Exposes the default instance's Configuration property.

```APIDOC
## configuration (static getter)

### Description
Exposes the default instance's Configuration property.

### Method
configuration (static getter)

### Signature
```ts
static get configuration(): Configuration
```

### Response
- **Configuration** - The Configuration instance of the default Actor instance.
```

--------------------------------

### ApifyFileSystemStorageBackend options and class definition

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

Defines the options interface and class for ApifyFileSystemStorageBackend. The options extend FileSystemStorageOptions and include an optional inputKey (default 'INPUT'). The class extends FileSystemStorageBackend and overrides keyValueStoreAdoptionCandidates and purgeKeyValueStore.

```typescript
export interface ApifyFileSystemStorageOptions extends FileSystemStorageOptions {
    inputKey?: string;   // default 'INPUT' — Configuration.inputKey (ACTOR_INPUT_KEY)
}

export class ApifyFileSystemStorageBackend extends FileSystemStorageBackend {
    constructor(options: ApifyFileSystemStorageOptions)
}
```

--------------------------------

### Access launch context info from BrowserController

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows how to access proxy and session information from the browserController's launchContext.

```javascript
const handlePageFunction = async ({ browserController }) => {
    // Information about the proxy used by the browser
    browserController.launchContext.proxyInfo;

    // Session used by the browser
    browserController.launchContext.session;
};
```

--------------------------------

### openKeyValueStore

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Opens a key-value store by id, name, or alias. Returns a KeyValueStore instance.

```APIDOC
## `openKeyValueStore`

### Description
Open a store by id, name, or alias (`null`/`undefined` = default). `KeyValueStore` is re-exported from `@crawlee/core`.

### Method
`async openKeyValueStore(storeIdOrName?: StorageIdentifier | null, options: OpenStorageOptions = {}): Promise<KeyValueStore>`

### Parameters
#### Path Parameters
- `storeIdOrName` (StorageIdentifier | null) - Optional - The id, name, or alias of the store. `null`/`undefined` uses the default store.
- `options` (OpenStorageOptions) - Optional - Additional options for opening the store.

### Response
Returns a promise that resolves to a `KeyValueStore` instance.

```

--------------------------------

### Initialize and exit an Actor with Actor.init() and Actor.exit()

Source: https://github.com/apify/apify-sdk-js/blob/master/README.md

Use Actor.init() to initialize the Actor and Actor.exit() to stop it. Retrieve input with Actor.getInput() and store output with Actor.setValue(). For multiple crawlers in one context, consider Actor.main().

```typescript
import { Actor } from 'apify';

await Actor.init();

const input = await Actor.getInput();
await Actor.setValue('OUTPUT', {
    message: 'Hello from Apify SDK!',
    input,
});

await Actor.exit();
```

--------------------------------

### ApifyFileSystemStorageBackend

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

Extends Crawlee's FileSystemStorageBackend to be Actor-input-aware. It adopts a bare file as the input record and spares input keys when the default store is purged.

```APIDOC
## ApifyFileSystemStorageBackend

### Description
Crawlee's `FileSystemStorageBackend` (from `@crawlee/fs-storage`), made Actor-input-aware: adopts a bare `<key>` or `<key>.json` file in the default store's directory as the input record when the store is opened (both files present fails the open), and spares the input keys (`INPUT` plus the configured `inputKey`, deduplicated) when the default store is purged on start (`purgeExcept`).

### Constructor
`new ApifyFileSystemStorageBackend(options: ApifyFileSystemStorageOptions)`

### Options
- **inputKey** (string) - Optional - Default `'INPUT'` - The key used for the input record. Corresponds to `Configuration.inputKey` (ACTOR_INPUT_KEY).
- Inherits all options from `FileSystemStorageOptions`.

### Overridden Methods (protected)
- **keyValueStoreAdoptionCandidates(options)** - Overrides the base method to include the input key adoption logic.
- **purgeKeyValueStore(store, options)** - Overrides the base method to spare input keys when purging.
```

--------------------------------

### PlatformEventManager init method

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/platform-event-manager.md

Initializes the base event manager and opens a WebSocket to the Actor-events stream when `configuration.actorEventsWsUrl` is set. Locally, it logs that ACTOR_EVENTS_WEBSOCKET_URL is not set and no platform events will be emitted.

```ts
override async init()
```

--------------------------------

### Create Proxy Configuration with Apify Proxy Groups and Country

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

Creates a proxy configuration using Apify Proxy with specified groups and a country code. This is the standard way to use Apify Proxy with rotation and country targeting.

```javascript
import { Actor } from 'apify';

// Apify Proxy with groups + country
const proxyConfiguration = await Actor.createProxyConfiguration({
    groups: ['GROUP1', 'GROUP2'],
    countryCode: 'US',
});
```

--------------------------------

### Actor.newClient method signatures

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Shows the instance and static signatures for Actor.newClient. Constructs an ApifyClient from configuration.

```typescript
newClient(options: ApifyClientOptions = {}): ApifyClient
static newClient(options: ApifyClientOptions = {}): ApifyClient
```

--------------------------------

### getEnv

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Parses all APIFY_* and ACTOR_* environment variables into an ApifyEnv snapshot.

```APIDOC
## getEnv

### Description
Parses all APIFY_* and ACTOR_* environment variables into an ApifyEnv snapshot.

### Method
getEnv

### Signature
```ts
getEnv(): ApifyEnv
static getEnv(): ApifyEnv
```

### Response
- **ApifyEnv** - An object containing fields such as `actorId`, `actorRunId`, `token`, `startedAt`, `defaultDatasetId`, `memoryMbytes`, `isAtHome`, `proxyPassword`, `inputKey`, `localStorageDir`, and more. `*_AT` variables become `Date`, integer variables are parsed, and missing/invalid values become `null`.
```

--------------------------------

### ChargingManager.init method signature

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/charging.md

Signature for the init method, which loads pricing info and charged-event counts, seeds charging state, and optionally creates a charge-log dataset. Throws errors on invalid configurations.

```typescript
async init(): Promise<void>
```

--------------------------------

### addWebhook

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Creates an ad-hoc webhook for the current run. Validates options with a strict zod schema and returns the created Webhook resource, or undefined locally.

```APIDOC
## addWebhook

### Description
Creates an ad-hoc webhook for the current run. Validates options with a strict zod schema (unknown keys rejected → `ArgumentValidationError` from `@apify/validations`). Locally, warns and returns `undefined`. Throws `Error` when `ACTOR_RUN_ID` is not set. Returns the created Webhook resource.

### Method
async

### Signature
```ts
async addWebhook(options: WebhookOptions): Promise<WebhookResource | undefined>
static async addWebhook(options: WebhookOptions): Promise<WebhookResource | undefined>
```

### Parameters
- **options** (WebhookOptions) - Required - Options for the webhook, including eventTypes and requestUrl.

### Request Example
```js
const webhook = await Actor.addWebhook({
    eventTypes: ['ACTOR.RUN.SUCCEEDED'],
    requestUrl: 'https://example.com/hook',
    idempotencyKey: Actor.getEnv().actorRunId,
});
```

### Response
Returns the created Webhook resource.

```

--------------------------------

### fail

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Same as exit but with exitCode 1 by default.

```APIDOC
## fail

### Description
Same as `exit` with `exitCode: 1` (unless overridden).

### Method
`fail`

### Signature
```ts
async fail(messageOrOptions?: string | ExitOptions, options: ExitOptions = {}): Promise<void>
static async fail(messageOrOptions?: string | ExitOptions, options: ExitOptions = {}): Promise<void>
```

### Parameters
- **messageOrOptions** (`string | ExitOptions`) - Optional - String = terminal status message; object = options
- **options.statusMessage** (`string`) - Optional - Terminal status message
- **options.timeoutSecs** (`number`) - Optional - Seconds to wait for event listeners (default `30`)
- **options.exitCode** (`number`) - Optional - Process exit code (default `1`)
- **options.exit** (`boolean`) - Optional - Whether to call `process.exit()` (default `true`)

### Example
```js
await Actor.fail('Something went wrong');
```
```

--------------------------------

### Updated launch options object for Apify.launchPuppeteer

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Shows the old and new ways to pass headless option. The new approach nests browser-specific options under launchOptions.

```javascript
// OLD
await Apify.launchPuppeteer({
    useChrome: true,
    headless: true,
});
```

```javascript
// NEW
await Apify.launchPuppeteer({
    useChrome: true,
    launchOptions: {
        headless: true,
    },
});
```

--------------------------------

### ProxyConfiguration methods

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

ProxyConfiguration methods that users can call directly: newUrl() and newProxyInfo().

```APIDOC
## `newUrl`

### Description
Returns a new proxy URL. For Apify Proxy, generates a URL with a fresh random session id; for custom `proxyUrls`, rotates round-robin via the base class.

### Request Example
```js
const url = await proxyConfiguration.newUrl();
console.log(url); // http://groups-XXX,session-xxxx,your-password@proxy.apify.com:8000
```

### Response
#### Success Response (200)
- **url** (string) - The new proxy URL with embedded session id.

```

```APIDOC
## `newProxyInfo`

### Description
Returns a fresh `ProxyInfo` object with a new proxy URL. Each call mints an independent URL with a random 12-char session id for Apify Proxy. A passed non-Apify `proxyInfo` is returned unchanged; a passed Apify-Proxy `proxyInfo` is refreshed onto the current endpoint, preserving username/session and its own groups/country.

### Request Example
```js
const info = await proxy.newProxyInfo();
```

### Response
#### Success Response (200)
- **url** (string) - Full proxy URL incl. credentials
- **username** (string) - Decoded username (e.g. `groups-XXX,session-abc,country-US`)
- **password** (string) - Decoded password
- **hostname** (string) - Proxy hostname
- **port** (string) - Proxy port
- **groups** (string[]) - (Apify Proxy only) configured groups
- **countryCode** / **subdivisionCode** (string) - (Apify Proxy only) when configured

```

--------------------------------

### Configuration constructor

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/configuration.md

Constructor for the Configuration class. Accepts optional field-level overrides, with environment variables taking precedence.

```APIDOC
## [CONSTRUCTOR] Configuration

### Description
Creates a new immutable Configuration instance. Field-level overrides are applied, but environment variables still take precedence over the provided options.

### Method
constructor

### Endpoint
new Configuration(options)

### Parameters
#### Constructor Parameters
- **options** (`ApifyConfigurationInput`) - Optional - Field-level overrides; env vars still take precedence.

### Request Example
```ts
const config = new Configuration({ token: 'my-token' });
```

### Response
#### Success Response
Returns a new `Configuration` instance.

#### Response Example
```ts
Configuration { token: 'my-token', ... }
```
```

--------------------------------

### Configuration.getGlobalConfiguration

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/configuration.md

Static method that returns the global Configuration singleton. It is created lazily and parses APIFY_* environment variables.

```APIDOC
## [STATIC METHOD] getGlobalConfiguration

### Description
Returns the SDK's global Configuration singleton, created lazily as `new Configuration()`. This singleton parses `APIFY_*` environment variables and serves as the fallback for code without an explicit configuration.

### Method
static getGlobalConfiguration

### Endpoint
Configuration.getGlobalConfiguration()

### Parameters
None.

### Request Example
```ts
const config = Configuration.getGlobalConfiguration();
```

### Response
#### Success Response
Returns the global `Configuration` singleton.

#### Response Example
```ts
Configuration { token: '...', headless: true, ... }
```
```

--------------------------------

### ApifyStorageBackend

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

The ApifyStorageBackend class implements the StorageBackend interface, bridging ApifyClient's synchronous resource accessors to crawlee's async factory interface. It is constructed with an ApifyClient instance and optional options.

```APIDOC
## ApifyStorageBackend

### Description
Bridges `apify-client`'s synchronous resource accessors (`dataset(id)`, `keyValueStore(id)`, `requestQueue(id, options)`) to crawlee's async factory interface. Constructor throws nothing; API errors from `apify-client` propagate.

### Constructor
`constructor(client: ApifyClient, options: ApifyStorageBackendOptions = {})`

### Parameters
- **client** (ApifyClient) - Required - The ApifyClient instance used to access the Apify platform API.
- **options** (ApifyStorageBackendOptions) - Optional - Configuration options for the storage backend.

### ApifyStorageBackendOptions
- **configuration** (Configuration) - Optional - Run's default storage ids + env values; without it, opening storages requires an explicit id or name.
- **requestQueueAccess** (RequestQueueAccessMode) - Optional - 'single' (default) | 'shared'.

### Usage Example
```ts
import { ApifyClient, ApifyStorageBackend, Dataset } from 'apify';

const client = new ApifyClient({ token });
const dataset = await Dataset.open(datasetId, { storageBackend: new ApifyStorageBackend(client) });
const { items } = await dataset.getData();
```

### Methods

#### storageExists
- **Signature**: `storageExists(id: string, type: StorageType): Promise<boolean>`
- **Description**: Returns `true` when `GET /v2/{kind}/{id}` returns a resource whose `id === id` (lets crawlee fall through to name-based lookup otherwise).

#### createDatasetBackend
- **Signature**: `createDatasetBackend(options?: StorageIdentifier): Promise<DatasetBackend>`
- **Description**: Resolves the identifier, returns an `ApifyDatasetBackend` around `client.dataset(id)`.

#### createKeyValueStoreBackend
- **Signature**: `createKeyValueStoreBackend(options?: StorageIdentifier): Promise<KeyValueStoreBackend>`
- **Description**: Returns an `ApifyKeyValueStoreBackend`.

#### createRequestQueueBackend
- **Signature**: `createRequestQueueBackend(options?: StorageIdentifier): Promise<RequestQueueBackend>`
- **Description**: Returns `ApifyRequestQueueSharedBackend` for `'shared'` access, else `ApifyRequestQueueSingleBackend`; client key = `actorRunId` (or random 32-char fallback).

#### getStorageBackendCacheKey
- **Signature**: `getStorageBackendCacheKey(): string`
- **Description**: Returns `ApifyStorageBackend:<sha256(publicBaseUrl+token)[:8]>` — partitions crawlee's storage cache per credentials.

### Identifier Resolution
- Explicit `id` wins; `name` → `getOrCreate(name)`; an alias (`{ alias }`, default `'__default__'`) maps to the run's default storage (from `defaultDatasetId`/`defaultKeyValueStoreId`/`defaultRequestQueueId`), or to a schema-declared storage from `ACTOR_STORAGES_JSON`, otherwise to an unnamed storage resolved through `resolveAliasId`.
- Aliases are persisted in the run's default key-value store record `__STORAGE_ALIASES_MAPPING` (keyed `<type>,<alias>,<credentials hash>`), so a migrated run reopens the same storages.
- Throws `Error` when `ACTOR_STORAGES_JSON` does not parse.

### Types
- `StorageType = 'Dataset' | 'KeyValueStore' | 'RequestQueue'`
- `DEFAULT_STORAGE_ALIAS = '__default__'`
```

--------------------------------

### Configure browserPoolOptions with lifecycle hooks

Source: https://github.com/apify/apify-sdk-js/blob/master/MIGRATIONS.md

Demonstrates configuring browserPoolOptions in PuppeteerCrawler, including retireBrowserAfterPageCount and a preLaunchHook that adjusts launch options based on request userData.

```javascript
const crawler = new Apify.PuppeteerCrawler({
    browserPoolOptions: {
        retireBrowserAfterPageCount: 10,
        preLaunchHooks: [
            async (pageId, launchContext) => {
                const { request } = crawler.crawlingContexts.get(pageId);
                if (request.userData.useHeadful === true) {
                    launchContext.launchOptions.headless = false;
                }
            },
        ],
    },
});
```

--------------------------------

### apifyClient (static getter)

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Exposes the default instance's ApifyClient property.

```APIDOC
## apifyClient (static getter)

### Description
Exposes the default instance's ApifyClient property.

### Method
apifyClient (static getter)

### Signature
```ts
static get apifyClient(): ApifyClient
```

### Response
- **ApifyClient** - The ApifyClient instance of the default Actor instance.
```

--------------------------------

### isAtHome

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/actor.md

Returns true when the APIFY_IS_AT_HOME environment variable is set.

```APIDOC
## isAtHome

### Description
Returns true when the APIFY_IS_AT_HOME environment variable is set.

### Method
isAtHome

### Signature
```ts
isAtHome(): boolean
static isAtHome(): boolean
```

### Response
- **boolean** - `true` if `APIFY_IS_AT_HOME` is set, otherwise `false`.
```

--------------------------------

### SmartApifyStorageBackend

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

Routes storage operations to cloud or local backends based on the environment. On the Apify platform, it always uses cloud storage; locally, it uses the local backend unless forceCloud is set, which requires an Apify token.

```APIDOC
## SmartApifyStorageBackend

### Description
Routes storages to cloud or local: on the platform (`configuration.isAtHome`) always cloud; locally the local backend, unless `forceCloud` (which throws an error when no token). Exposes `getSuitableStorageBackend(options)` so `forceCloud` reuses the same cloud backend instance.

### Constructor
`new SmartApifyStorageBackend(options: SmartApifyStorageBackendOptions)`

### Options
- **cloudStorageBackend** (StorageBackend) - Required - The cloud storage backend.
- **localStorageBackend** (StorageBackend) - Required - The local storage backend.
- **configuration** (Configuration) - Required - The configuration object.

### Methods
- **getSuitableStorageBackend(options: OpenStorageOptions = {}): StorageBackend** - Returns the appropriate storage backend based on the environment and options.
- **createDatasetBackend** - Delegates to the suitable storage backend.
- **createKeyValueStoreBackend** - Delegates to the suitable storage backend.
- **createRequestQueueBackend** - Delegates to the suitable storage backend.
- **stats** - Delegates to the suitable storage backend.
- **getStorageBackendCacheKey** - Delegates to the suitable storage backend.
- **storageExists** - Declared unconditionally, delegating with optional chaining.
- **purge** - Declared unconditionally, delegating with optional chaining.
- **teardown** - Declared unconditionally, delegating with optional chaining.

### Error Handling
When `forceCloud` is used without an Apify token, throws: `Error('In order to use the Apify cloud storage from your computer, you need to provide an Apify token using the APIFY_TOKEN environment variable.')`
```

--------------------------------

### ChargingStorageBackend options and class declaration

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/storage-backends.md

Defines the options interface and class for a storage backend that wraps another backend to charge default dataset pushes. The class conditionally exposes storageExists, purge, and teardown only when the inner backend has them.

```typescript
export interface ChargingStorageBackendOptions {
    configuration: Configuration;
    getChargingManager: () => ChargingManager;
}

export class ChargingStorageBackend implements StorageBackend {
    constructor(inner: StorageBackend, options: ChargingStorageBackendOptions)
    storageExists?: StorageBackend['storageExists'];   // present only when inner has it
    purge?: StorageBackend['purge'];
    teardown?: StorageBackend['teardown'];
}
```

--------------------------------

### ProxyConfiguration constructor signature

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

The constructor signature for ProxyConfiguration. It takes options and an optional Configuration instance, defaulting to the global singleton.

```typescript
constructor(options: ProxyConfigurationOptions = {}, readonly configuration = Configuration.getGlobalConfiguration())
```

--------------------------------

### initialize method signature

Source: https://github.com/apify/apify-sdk-js/blob/master/_autodocs/api-reference/proxy-configuration.md

TypeScript signature for the initialize method. It loads the proxy password from the Apify API when a token is available and none was given, then checks access unless checkAccess is false. Throws on platform when no password can be obtained or when the status check reports not connected.

```typescript
async initialize(options?: { checkAccess?: boolean }): Promise<boolean>
```
Tokens:
Raw