Apify API Client for JavaScript

https://github.com/apify/apify-client-js
Admin
The official Apify API client for JavaScript, simplifying access to the Apify API with features like...
Tokens:98,237
Snippets:758
Trust Score:9.9
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### start() basic example

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

Starts an Actor with input and logs the run ID and status.

```javascript
const run = await client.actor('my-actor').start({ url: 'https://example.com' });
console.log(`Run started: ${run.id}, status: ${run.status}`);
```

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

### start() advanced example

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

Starts an Actor with specific build, memory, timeout, and webhook notification.

```javascript
// Advanced: specific build, memory, and webhook notification
const run = await client.actor('my-actor').start(
    { url: 'https://example.com' },
    {
        build: 'beta',
        memory: 512,
        timeout: 300,
        webhooks: [{ eventTypes: ['ACTOR.RUN.SUCCEEDED'], requestUrl: 'https://my.app/hook' }],
    },
);
```

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

### list() usage example

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/build-clients.md

Example of calling list() with limit and desc options to get the first 5 builds, newest first.

```javascript
const { items } = await client.builds().list({ limit: 5, desc: true });
```

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

### get() usage example

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

JavaScript example showing how to retrieve the current user's data and access fields like username and plan.

```javascript
const user = await client.user().get();   // current user ('me')
console.log(user.username, user.plan?.maxMonthlyUsageUsd);
```

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

### Get actor version example

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

Example of using the get() method to retrieve an actor version and log its buildTag.

```javascript
const version = await client.actor('my-actor').version('0.1').get();
console.log(version?.buildTag); // e.g. 'latest'
```

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

### ApifyClient Instantiation Example

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

Example of creating an ApifyClient instance with custom options.

```javascript
const { ApifyClient } = require('apify-client');

const client = new ApifyClient({
    token: 'MY-APIFY-TOKEN',
    maxRetries: 5,
    minDelayBetweenRetriesMillis: 250,
    timeoutSecs: 120,
});
```

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

### Install Apify Client with Bun

Source: https://github.com/apify/apify-client-js/blob/master/docs/01_introduction/index.md

Install the apify-client package using Bun.

```bash
bun add apify-client
```

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

### get() usage example

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

Fetches a dataset by ID and logs its item count.

```javascript
const dataset = await client.dataset('my-dataset').get();
console.log(dataset?.itemCount);
```

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

### RunClient Usage Examples

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/run-clients.md

Examples of using the RunClient methods.

```javascript
const run = await client.run('run-id').get({ waitForFinish: 60 });
console.log(run?.status);
```

```javascript
const run = await client.run('run-id').waitForFinish({ waitSecs: 300 });
if (run.status === 'SUCCEEDED') console.log('done');
```

```javascript
const { items } = await client.run('run-id').dataset().listItems();
```

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

### Get or create a named request queue

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/request-queue-collection-client.md

Example of getting or creating a request queue named 'my-queue'.

```javascript
const queue = await client.requestQueues().getOrCreate('my-queue');
```

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

### create() usage example

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

JavaScript example showing how to create a new actor version using a Git repository source.

```javascript
const newVersion = await client.actor('my-actor').versions().create({
    versionNumber: '0.2',
    sourceType: ActorSourceType.GitRepo,
    gitRepoUrl: 'https://github.com/me/my-actor',
    buildTag: 'latest',
});
```

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

### start() method signature

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

TypeScript signature for the start() method. Starts an Actor and returns the ActorRun object immediately.

```typescript
async start(input?: unknown, options: ActorStartOptions = {}): Promise<ActorRun>
```

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

### KeyValueStore Client Code Examples

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/key-value-store-client.md

Code examples for the KeyValueStore client methods.

```javascript
const record = await client.keyValueStore('my-store').getRecord('OUTPUT');
console.log(record?.value, record?.contentType);
```

```javascript
try {
    const record = await client.keyValueStore('my-store').getRecord('screenshot.png', { buffer: true });
    if (record) console.log(record.value); // Buffer
} catch (err) {
    console.error('Failed to fetch record', err);
}
```

```javascript
await client.keyValueStore('my-store').setRecord({ key: 'OUTPUT', value: { crawledUrls: 100 } });
```

```javascript
const imageBuffer = await fetchStaticFile('screenshot.png');
await client.keyValueStore('my-store').setRecord(
    { key: 'screenshot.png', value: imageBuffer, contentType: 'image/png' },
    { doNotRetryTimeouts: true },
);
```

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

### Install Apify Client with NPM

Source: https://github.com/apify/apify-client-js/blob/master/docs/01_introduction/index.md

Install the apify-client package using NPM.

```bash
npm i apify-client
```

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

### Install Apify Client with Yarn

Source: https://github.com/apify/apify-client-js/blob/master/docs/01_introduction/index.md

Install the apify-client package using Yarn.

```bash
yarn add apify-client
```

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

### updateLimits() usage example

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

JavaScript example showing how to update the monthly usage cap to 100 USD.

```javascript
await client.user().updateLimits({ maxMonthlyUsageUsd: 100 });
```

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

### Install Apify Client with PNPM

Source: https://github.com/apify/apify-client-js/blob/master/docs/01_introduction/index.md

Install the apify-client package using PNPM.

```bash
pnpm add apify-client
```

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

### monthlyUsage() usage example

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

JavaScript example showing how to retrieve monthly usage for a specific user and log the total usage credits after volume discount.

```javascript
const usage = await client.user('john-doe').monthlyUsage();
console.log(usage?.totalUsageCreditsUsdAfterVolumeDiscount);
```

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

### limits() usage example

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

JavaScript example showing how to retrieve limits and current usage, then log the used amount against the maximum.

```javascript
const { limits, current } = await client.user().limits();
console.log(`used ${current.monthlyUsageUsd} of ${limits.maxMonthlyUsageUsd} USD`);
```

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

### create() usage example

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

Example usage of create() to create a new Actor.

```javascript
const newActor = await client.actors().create({
    name: 'my-actor',
    title: 'My Actor',
    isPublic: false,
});
```

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

### Install dependencies with pnpm

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

Install project dependencies using pnpm.

```bash
pnpm install
```

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

### StreamedLog.start()

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

Starts the log redirection process. Throws an error if already started.

```APIDOC
## StreamedLog.start()

### Description
Starts log redirection. Throws an `Error('Streaming task already active')` if the streaming task is already active.

### Method
N/A (class method)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
const streamedLog = await client.run('run-id').getStreamedLog({ fromStart: false });
streamedLog?.start();
```

### Response
#### Success Response
- **void** - No return value.

#### Error Handling
- **Error** - Throws `Error('Streaming task already active')` if already started.
```

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

### Get and Start Actor using Resource Client

Source: https://github.com/apify/apify-client-js/blob/master/docs/02_concepts/01_usage-patterns.md

Use the `ActorClient` to fetch details of a specific actor or to start a new run for it. Resource identification can be done using the resource ID or username/resource-name.

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });

// Resource clients accept an ID of the resource.
const actorClient = client.actor('username/actor-name');
// Fetches the john-doe/my-actor object from the API.
const myActor = await actorClient.get();
// Starts the run of john-doe/my-actor and returns the Run object.
const myActorRun = await actorClient.start();
```

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

### start()

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

Starts the Actor and returns the Run object immediately without waiting for the run to finish.

```APIDOC
## start()

### Description
Starts the Actor and returns the Run object immediately without waiting for the run to finish.

### Method
POST

### Endpoint
/v2/actors/{id}/runs

### Parameters
#### Path Parameters
- **id** (string) - Required - The Actor ID.

#### Request Body
- **input** (unknown) - Optional - Actor input; any JSON-serializable value, or string/Buffer when `contentType` is set.

#### Query Parameters
- **build** (string) - Optional - Build tag or number (e.g. `'beta'`, `'1.2.345'`).
- **contentType** (string) - Optional - Sets the request `content-type` header.
- **memory** (number) - Optional - Memory in MB.
- **timeout** (number) - Optional - Run timeout in seconds; `0` = no timeout.
- **waitForFinish** (number) - Optional - Server-side wait up to 60 s.
- **webhooks** (readonly WebhookUpdateData[]) - Optional - Ad-hoc webhooks, base64-encoded as a query param.
- **maxItems** (number) - Optional - Max charged dataset items (pay-per-result Actors); non-negative.
- **maxTotalChargeUsd** (number) - Optional - Max cost in USD (pay-per-event Actors); non-negative.
- **restartOnError** (boolean) - Optional - Restart run when it fails.
- **forcePermissionLevel** (ACTOR_PERMISSION_LEVEL) - Optional - Override run permissions.

### Request Example
```javascript
const run = await client.actor('my-actor').start({ url: 'https://example.com' });
console.log(`Run started: ${run.id}, status: ${run.status}`);
```

### Response
#### Success Response (200)
- **ActorRun** - The run object.

#### Response Example
```json
{
  "id": "string",
  "status": "string"
}
```

### Error Handling
- **ApifyApiError** - Thrown for invalid input (e.g., 400).
- **ow validation error** - Thrown for unknown option keys.
```

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

### ActorClient Usage Examples

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

Code examples demonstrating usage of the ActorClient methods.

```javascript
const build = await client.actor('my-actor').build('0.1', { tag: 'latest', waitForFinish: 120 });
console.log(build.status);
```

```javascript
const lastSucceeded = await client.actor('my-actor').lastRun({ status: 'SUCCEEDED' }).get();
```

```javascript
client.actor('my-actor').runs().list({ limit: 10, desc: true });
```

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

### Start Actor and Fetch Dataset Items

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

This snippet demonstrates how to initialize the ApifyClient, start an actor, and then fetch the resulting dataset items. Ensure you have your Apify API token configured.

```javascript
const { ApifyClient } = require('apify-client');

const client = new ApifyClient({
    token: 'MY-APIFY-TOKEN',
});

// Starts an actor and waits for it to finish.
const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();
// Fetches results from the actor's dataset.
const { items } = await client.dataset(defaultDatasetId).listItems();
```

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

### Get or create a shared queue and add a request

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/request-queue-collection-client.md

Example of getting or creating a named queue for sharing across Actor runs, then adding a request to it.

```javascript
// Named queues are ideal for sharing datasets across Actor runs
const queue = await client.requestQueues().getOrCreate('shared-crawl-queue');
await client.requestQueue(queue.id).addRequest({ url: 'https://example.com', uniqueKey: 'example' });
```

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

### Get or create a store by name

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/key-value-store-collection-client.md

Gets or creates a key-value store with the name 'my-store'.

```javascript
const store = await client.keyValueStores().getOrCreate('my-store');
```

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

### ActorStartOptions interface

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

Options for the start() method, including build, memory, timeout, webhooks, and more.

```typescript
interface ActorStartOptions {
    build?: string;
    contentType?: string;
    memory?: number;
    timeout?: number;
    waitForFinish?: number;
    webhooks?: readonly WebhookUpdateData[];
    maxItems?: number;
    maxTotalChargeUsd?: number;
    restartOnError?: boolean;
    forcePermissionLevel?: ACTOR_PERMISSION_LEVEL;
}
```

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

### ActorEnvVarCollectionClient create() method and usage

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

Shows the create() method signature and a usage example that creates an environment variable for a specific actor version. The example sets name, value, and isSecret fields.

```ts
async create(actorEnvVar: ActorEnvironmentVariable): Promise<ActorEnvironmentVariable>
```

```javascript
await client.actor('my-actor').version('0.1').envVars().create({
    name: 'MY_VAR',
    value: 'my-value',
    isSecret: false,
});
```

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

### list() usage example

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

JavaScript example showing how to list actor versions and destructure the items from the result.

```javascript
const { items } = await client.actor('my-actor').versions().list();
```

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

### WebhookClient code examples

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/webhook-clients.md

Code examples for WebhookClient methods and types.

```ts
async get(): Promise<Webhook | undefined>
```

```ts
async update(newFields: WebhookUpdateData): Promise<Webhook>
```

```ts
export type WebhookUpdateData = Partial<
    Pick<
        Webhook,
        | 'isAdHoc'
        | 'condition'
        | 'ignoreSslErrors'
        | 'doNotRetry'
        | 'requestUrl'
        | 'payloadTemplate'
        | 'shouldInterpolateStrings'
        | 'isApifyIntegration'
        | 'headersTemplate'
        | 'description'
    > & {
        eventTypes: readonly WebhookEventType[];
    }
> & WebhookIdempotencyKey;

// WebhookIdempotencyKey: { idempotencyKey?: string }
```

```javascript
await client.webhook('webhook-id').update({
    eventTypes: ['ACTOR.RUN.SUCCEEDED'],
    requestUrl: 'https://example.com/webhook',
    headersTemplate: '{"Authorization": "Bearer {{token}}"}',
});
```

```ts
async delete(): Promise<void>
```

```ts
async test(): Promise<WebhookDispatch | undefined>
```

```javascript
const dispatch = await client.webhook('webhook-id').test();
console.log(dispatch?.status);
```

```ts
dispatches(): WebhookDispatchCollectionClient
```

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

### RequestQueueClient Usage Examples

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/request-queue-client.md

Example usage of the RequestQueueClient methods.

```javascript
const { items } = await client.requestQueue('my-queue').listHead({ limit: 5 });
```

```javascript
const result = await client.requestQueue('my-queue').addRequest(
    { url: 'https://example.com', uniqueKey: 'example', userData: { depth: 0 } },
    { forefront: true },
);
console.log(result.wasAlreadyPresent); // false on first add
```

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

### addRequest() usage example

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/request-queue-client.md

JavaScript example showing how to add a request with forefront option and log the result.

```javascript
const result = await client.requestQueue('my-queue').addRequest(
    { url: 'https://example.com', uniqueKey: 'example', userData: { depth: 0 } },
    { forefront: true },
);
console.log(result.wasAlreadyPresent); // false on first add
```

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

### StreamedLog.start() and stop() - Redirect run log

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

Starts and stops log redirection. `start()` throws Error('Streaming task already active') if already started. `stop()` throws Error('Streaming task is not active') if not started, and swallows AbortErrors from the stream.

```javascript
const streamedLog = await client.run('run-id').getStreamedLog({ fromStart: false });
streamedLog?.start();
try {
    await client.run('run-id').waitForFinish({ waitSecs: 300 });
} finally {
    await streamedLog?.stop();
}
```

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

### Get or create with error handling and setRecord

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/key-value-store-collection-client.md

Gets or creates a store with a schema, handles errors, and then sets a record in the store.

```javascript
// Get-or-create with error handling
let store;
try {
    store = await client.keyValueStores().getOrCreate('assets', { schema: { exampleField: 'string' } });
} catch (err) {
    console.error('Could not obtain store', err);
    return;
}
await client.keyValueStore(store.id).setRecord({ key: 'banner.png', value: imageBytes });
```

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

### listHead() usage example

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/request-queue-client.md

JavaScript example showing how to call listHead() with a limit of 5 and destructure the items.

```javascript
const { items } = await client.requestQueue('my-queue').listHead({ limit: 5 });
```

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

### Get or Create a Dataset

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

Shows how to get an existing dataset or create a new one if it doesn't exist. This is useful for managing datasets by name.

```javascript
// Collection clients do not require a parameter.
const datasetCollectionClient = apifyClient.datasets();
// Gets (or creates, if it doesn't exist) a dataset with the name of my-dataset.
const myDataset = await datasetCollectionClient.getOrCreate('my-dataset');
```

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

### listAndLockHead() usage example

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/request-queue-client.md

JavaScript example showing how to lock requests and release the lock after processing.

```javascript
const { items } = await client.requestQueue('my-queue').listAndLockHead({ lockSecs: 60, limit: 10 });
for (const request of items) {
    processRequest(request);
    await client.requestQueue('my-queue').deleteRequestLock(request.id); // release when done
}
```

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

### get()

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

Gets an environment variable for a specific actor version.

```APIDOC
## [GET] /actor-env-var

### Description
Retrieves an environment variable for a specific actor version.

### Method
GET

### Endpoint
`/actor-env-var`

### Parameters
#### Path Parameters
- **actorId** (string) - Required - Actor ID.
- **versionNumber** (string) - Required - Version number.
- **envVarName** (string) - Required - Environment variable name.

### Request Example
```javascript
const envVar = await client.actor('my-actor').version('0.1').envVar('MY_VAR').get();
```

### Response
#### Success Response (200)
- **name** (string) - Environment variable name.
- **value** (string) - Environment variable value.

#### Response Example
```json
{
  "name": "MY_VAR",
  "value": "some-value"
}
```
```

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

### list() usage example

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

Example usage of list() to fetch actors and iterate all pages.

```javascript
const { items } = await client.actors().list({ my: true, limit: 20 });

// iterate all pages
for await (const actor of client.actors().list()) {
    console.log(actor.name);
}
```

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

### RunGetOptions

Source: https://github.com/apify/apify-client-js/blob/master/docs/public-api/apify-client.api.md

Options for getting a run.

```APIDOC
## RunGetOptions

### Description
Options for getting a run.

### Properties
- **waitForFinish** (number) - Optional - Number of seconds to wait for the run to finish before returning.

```

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

### dataset() example

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/run-clients.md

Returns a DatasetClient for the run's default dataset, allowing access to its items.

```javascript
const { items } = await client.run('run-id').dataset().listItems();
```

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

### Iterate store search results example

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

Example of iterating through store search results with error handling.

```javascript
// Iterate search results page by page with error handling
try {
    for await (const actor of client.store().list({ category: 'SCRAPING', username: 'apify', chunkSize: 20 })) {
        console.log(actor.name, actor.url);
    }
} catch (err) {
    console.error('Store search failed', err);
}
```

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

### List store actors example

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

Example of listing store actors with a search query.

```javascript
const client = new ApifyClient(); // no token required
const { items, total } = await client.store().list({ search: 'web scraper', limit: 10 });
console.log(`${items.length} of ${total} matching Actors`);
```

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

### Start Actor with Timeout

Source: https://github.com/apify/apify-client-js/blob/master/docs/02_concepts/03_convenience-functions.md

Use the `start()` function with the `waitForFinish` option to initiate an Actor run and set a maximum waiting time. The promise resolves with the run status if the timeout is reached before completion.

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });

// Starts an Actor and waits maximum 60s for the finish
const { status } = await client.actor('username/actor-name').start({
    waitForFinish: 60, // 1 minute
});
```

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

### Start and Wait for Actor Run

Source: https://github.com/apify/apify-client-js/blob/master/docs/02_concepts/03_convenience-functions.md

Use the `call()` function to start an Actor and wait for its completion. This is useful for synchronous execution of Actor tasks.

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });

// Starts an Actor and waits for it to finish.
const finishedActorRun = await client.actor('username/actor-name').call();
```

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

### Update actor version example

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

Example of updating an actor version's buildTag to 'latest'.

```javascript
await client.actor('my-actor').version('0.1').update({ buildTag: 'latest' });
```

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

### call() basic example

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

Calls an Actor and logs the final run status.

```javascript
const run = await client.actor('my-actor').call({ url: 'https://example.com' });
console.log(run.status); // e.g. 'SUCCEEDED'
```

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

### listItems() usage example

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

Fetches the first page of items and iterates over all pages in chunks.

```javascript
const { items, total } = await client.dataset('my-dataset').listItems({ limit: 100 });
console.log(`Got ${items.length} of ${total}`);

// iterate all pages in chunks of 1000
for await (const item of client.dataset('my-dataset').listItems({ fields: ['url', 'title'], chunkSize: 1000 })) {
    console.log(item);
}
```

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

### Adding Mock Routes

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

Example of adding a mock route in the mock server.

```typescript
// test/mock_server/routes/my_resource.ts
import { Router } from 'express';

export function addMyResourceRoutes(router: Router) {
    router.get('/v2/my-resources/:id', (req, res) => {
        res.json({ data: { id: req.params.id } });
    });
}
```

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

### Get actor and log name and createdAt

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

Example usage of get(). Checks for undefined before accessing fields; createdAt is a Date object.

```javascript
const actor = await client.actor('john-doe/my-actor').get();
if (actor) {
    console.log(actor.name, actor.createdAt); // createdAt is a Date
}
```

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

### POST /v2/actors/{id}/runs

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/endpoints.md

Starts a run of the specified actor.

```APIDOC
## POST /v2/actors/{id}/runs

### Description
Starts a run of the specified actor.

### Method
POST

### Endpoint
/v2/actors/{id}/runs

### Parameters
#### Path Parameters
- **id** (string) - Required - Actor ID or `username/actor-name`.

#### Query Parameters
- **waitForFinish** (number) - Optional - Time to wait for the run to finish.
- **timeout** (number) - Optional - Timeout for the run.
- **memory** (number) - Optional - Memory limit for the run.
- **build** (string) - Optional - Build to use.
- **webhooks** (string) - Optional - Base64 JSON array of webhook URLs.
- **maxItems** (number) - Optional - Maximum number of items.
- **maxTotalChargeUsd** (number) - Optional - Maximum total charge in USD.
- **restartOnError** (boolean) - Optional - Whether to restart on error.
- **forcePermissionLevel** (string) - Optional - Force permission level.

#### Request Body
- **input** (object) - Optional - The input for the actor run.

### Response
#### Success Response (200)
- **ActorRun** (object) - The created actor run object.

#### Response Example
```json
{
  "id": "string",
  "status": "string"
}
```
```

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

### get()

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/key-value-store-client.md

Retrieves a key-value store by ID. Returns undefined if the store does not exist (404 is swallowed).

```javascript
const store = await client.keyValueStore('my-store').get();
console.log(store?.stats);
```

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

### get() method signature and usage

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/key-value-store-client.md

Retrieves a key-value store. Returns undefined on 404. Has a 5-second timeout.

```typescript
async get(): Promise<KeyValueStore | undefined>
```

```javascript
const store = await client.keyValueStore('my-store').get();
console.log(store?.stats);
```

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

### setRecord() basic example

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/key-value-store-client.md

Stores a simple object record with auto-detected content type.

```javascript
await client.keyValueStore('my-store').setRecord({ key: 'OUTPUT', value: { crawledUrls: 100 } });
```

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

### Get schedule with ScheduleClient.get()

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/schedule-clients.md

Retrieves a schedule by its ID. Returns the Schedule object or undefined if not found. The example shows how to call get() and access the cronExpression and nextRunAt properties.

```ts
async get(): Promise<Schedule | undefined>
```

```javascript
const schedule = await client.schedule('schedule-id').get();
console.log(schedule?.cronExpression, schedule?.nextRunAt);
```

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

### Build the project

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

Build the project using pnpm.

```bash
pnpm build
```

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

### get()

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/build-clients.md

Retrieves a build by its ID. Optionally waits for the build to finish on the server side.

```APIDOC
## GET /v2/actor-builds/{id}

### Description
Retrieves a build by its ID. Optionally waits for the build to finish on the server side.

### Method
GET

### Endpoint
/v2/actor-builds/{id}

### Parameters
#### Query Parameters
- **waitForFinish** (number) - Optional - Server-side wait in seconds (max 60). Default: 0.

### Request Example
```
GET /v2/actor-builds/{id}?waitForFinish=60
```

### Response
#### Success Response (200)
- **Build** (object) - The build object.

#### Response Example
```json
{
  "id": "build-id",
  "status": "SUCCEEDED"
}
```

```

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

### TaskClient

Source: https://github.com/apify/apify-client-js/blob/master/docs/public-api/apify-client.api.md

The TaskClient class provides methods to manage and execute tasks on the Apify platform. It includes operations to get, update, delete, start, call, and manage task inputs and runs.

```APIDOC
## TaskClient

### Description
Provides methods to manage and execute tasks on the Apify platform.

### Methods

#### constructor(options: ApiClientSubResourceOptions)
Initializes a new instance of TaskClient.

#### call(input?: Dictionary, options?: TaskCallOptions): Promise<ActorRun>
Starts a task and waits for it to finish, returning the run details.

#### delete(): Promise<void>
Deletes the task.

#### get(): Promise<Task | undefined>
Retrieves the task details.

#### getInput(): Promise<Dictionary | Dictionary[] | undefined>
Retrieves the task input.

#### lastRun(options?: TaskLastRunOptions): RunClient
Returns a client for the last run of the task.

#### publish(): Promise<Task>
Publishes the task.

#### runs(): RunCollectionClient
Returns a client for the task's runs.

#### start(input?: Dictionary, options?: TaskStartOptions): Promise<ActorRun>
Starts the task and returns the run details.

#### unpublish(): Promise<Task>
Unpublishes the task.

#### update(newFields: TaskUpdateData): Promise<Task>
Updates the task with the given fields.

#### updateInput(newFields: Dictionary | Dictionary[]): Promise<Dictionary | Dictionary[]>
Updates the task input.

#### webhooks(): WebhookCollectionClient
Returns a client for the task's webhooks.

```

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

### ActorClient

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

Documentation for the ActorClient class, including constructor, get, update, and delete methods.

```APIDOC
## ActorClient

`export class ActorClient extends ResourceClient` — source: `src/resource_clients/actor.ts:43`. Imported from the package root. Obtain instances via `ApifyClient.actor(id)` (`src/apify_client.ts:158`) — never construct directly (constructor marked `@hidden`).

```ts
// package root import
import { ActorClient, Actor, ActorRun, ActorStartOptions, ActorCallOptions } from 'apify-client';

const actorClient = new ApifyClient({ token: 'my-token' }).actor('john-doe/my-cool-actor');
```

Resource path: `actors`. Runs, builds, versions, and webhooks are nested sub-resources.

## Constructor (hidden)

```ts
constructor(options: ApiClientSubResourceOptions)
```

`ApiClientSubResourceOptions` (`src/base/api_client.ts:31`) expands to:

```ts
type ApiClientSubResourceOptions = Omit<ApiClientOptions, 'resourcePath'>;

// where ApiClientOptions is:
interface ApiClientOptions {
    baseUrl: string;
    publicBaseUrl: string;
    resourcePath: string;
    apifyClient: ApifyClient;
    httpClient: HttpClient;
    id?: string;
    params?: Record<string, unknown>;
}
```

## Methods

### get()

```ts
async get(): Promise<Actor | undefined>
```

Gets the `Actor` object from the API. `undefined` if it does not exist (404 with `type: record-not-found` is swallowed).

**Returns**: `Actor` (see [types.md](../types.md) for the full field list) or `undefined`.

```javascript
const actor = await client.actor('john-doe/my-actor').get();
if (actor) {
    console.log(actor.name, actor.createdAt); // createdAt is a Date
}
```

### update()

```ts
async update(newFields: ActorUpdateOptions): Promise<Actor>
```

Updates the Actor. `ActorUpdateOptions` — `Partial<Pick<Actor, 'name' | 'description' | 'isPublic' | 'isDeprecated' | 'seoTitle' | 'seoDescription' | 'title' | 'restartOnError' | 'versions' | 'categories' | 'actor.ts:676'>>`.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `newFields` | `ActorUpdateOptions` | yes | — | Fields to update |

**Throws**: `ApifyApiError` for API errors (e.g. 400 validation); `ow` error when `newFields` is not an object.

```javascript
await client.actor('john-doe/my-actor').update({ title: 'New title', isPublic: true });
```

### delete()

```ts
async delete(): Promise<void>
```

Deletes the Actor. 404 is swallowed.

```javascript
await client.actor('john-doe/my-actor').delete();
```
```

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

### GET /v2/actors/runs/last

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/endpoints.md

Gets the last run of an actor.

```APIDOC
## GET /v2/actors/runs/last

### Description
Gets the last run of an actor.

### Method
GET

### Endpoint
/v2/actors/runs/last

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by run status.
- **origin** (string) - Optional - Filter by run origin.

### Response
#### Success Response (200)
- **RunClient** (object) - The run client with `id: 'last'`.

#### Response Example
```json
{
  "id": "last"
}
```
```

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

### Run the tests

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

Run the test suite to verify everything works.

```bash
pnpm test
```

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

### get()

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

Retrieves user data. With a token it returns private data for yourself or public data for other users.

```APIDOC
## get()

### Description
Retrieves user data. With a token it returns private data for yourself or public data for other users.

### Method
GET

### Endpoint
`/v2/users/{id}`

### Parameters
#### Path Parameters
- `id` (string) - Required - User ID or 'me' for the current user.

### Response
#### Success Response (200)
- `username` (string) - Username
- `profile` (object) - Profile object with optional fields: `bio`, `name`, `pictureUrl`, `githubUsername`, `websiteUrl`, `twitterUsername`
- `id` (string, private) - Private user ID
- `email` (string, private) - Email
- `proxy` (UserProxy, private) - Proxy object with `password` and `groups`
- `plan` (UserPlan, private) - Plan info including `maxMonthlyUsageUsd`, `maxActorMemoryGbytes`, `maxActorCount`, `dataRetentionDays`, `enabledPlatformFeatures`
- `effectivePlatformFeatures` (EffectivePlatformFeatures, private) - Per-feature settings
- `createdAt` (Date, private) - Creation time
- `isPaying` (boolean, private) - Paying status

#### Response Example
```json
{
  "username": "john-doe",
  "profile": {
    "bio": "...",
    "name": "John Doe",
    "pictureUrl": "...",
    "githubUsername": "...",
    "websiteUrl": "...",
    "twitterUsername": "..."
  },
  "id": "...",
  "email": "...",
  "proxy": {
    "password": "...",
    "groups": []
  },
  "plan": {
    "maxMonthlyUsageUsd": 100,
    "maxActorMemoryGbytes": 2048,
    "maxActorCount": 10,
    "dataRetentionDays": 30,
    "enabledPlatformFeatures": []
  },
  "effectivePlatformFeatures": {},
  "createdAt": "2023-01-01T00:00:00.000Z",
  "isPaying": true
}
```

### Example
```javascript
const user = await client.user().get();   // current user ('me')
console.log(user.username, user.plan?.maxMonthlyUsageUsd);
```
```

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

### GET /v2/actors/{id}/builds/default

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/endpoints.md

Gets the default build of an actor.

```APIDOC
## GET /v2/actors/{id}/builds/default

### Description
Gets the default build of an actor.

### Method
GET

### Endpoint
/v2/actors/{id}/builds/default

### Parameters
#### Path Parameters
- **id** (string) - Required - Actor ID or `username/actor-name`.

#### Query Parameters
- **waitForFinish** (number) - Optional - Time to wait for the build to finish.

### Response
#### Success Response (200)
- **BuildClient** (object) - The resolved build client.

#### Response Example
```json
{
  "id": "string"
}
```
```

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

### Clone and navigate to the repository

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

Clone the forked repository and change into the project directory.

```bash
git clone git@github.com:<your-username>/apify-client-js.git
cd apify-client-js
```

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

### GET /v2/actors/{id}/versions/{versionNumber}

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/endpoints.md

Gets a specific actor version.

```APIDOC
## GET /v2/actors/{id}/versions/{versionNumber}

### Description
Gets a specific actor version.

### Method
GET

### Endpoint
/v2/actors/{id}/versions/{versionNumber}

### Parameters
#### Path Parameters
- **id** (string) - Required - Actor ID or `username/actor-name`.
- **versionNumber** (string) - Required - Version number.

### Response
#### Success Response (200)
- **ActorVersion** (object) - The actor version object.

#### Response Example
```json
{
  "versionNumber": "string"
}
```
```

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

### Initialize ApifyClient and Manage Actors

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

Demonstrates initializing the ApifyClient with a token and managing actors. Use this to create, list, or get actor resources.

```javascript
const { ApifyClient } = require('apify-client');
const apifyClient = new ApifyClient({ token: 'my-token' });

// Collection clients do not require a parameter.
const actorCollectionClient = apifyClient.actors();
// Creates an actor with the name: my-actor.
const myActor = await actorCollectionClient.create({ name: 'my-actor' });
// Lists all of your actors.
const { items } = await actorCollectionClient.list();
```

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

### Build a Webhook Listener with Express

Source: https://github.com/apify/apify-client-js/blob/master/docs/03_guides/01_examples.md

This example demonstrates how to set up an Express.js server to receive and process webhook payloads from Apify. It logs the payload and downloads the dataset associated with the run.

```javascript
import express from 'express';
import bodyParser from 'body-parser';
import { ApifyClient, DownloadItemsFormat } from 'apify-client';

// Initialize Apify client, express and define server port
const client = new ApifyClient({ token: 'MY_APIFY_TOKEN' });
const app = express();
const PORT = 3000;

// Tell express to use body-parser's JSON parsing
app.use(bodyParser.json());

app.post('apify-webhook', async (req, res) => {
    // Log the payload from the webhook
    console.log(req.body);

    const runDataset = await client.dataset(req.body.resource.defaultDatasetId);

    // e.g. Save dataset locally as JSON
    await runDataset.downloadItems(DownloadItemsFormat.JSON);

    // Respond to the webhook
    res.send('Webhook received');
});

// Start express on the defined port
app.listen(PORT, () => console.log(`🚀 Server running on port ${PORT}`));
```

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

### Available pnpm scripts for build, test, lint, and format

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

Lists all available pnpm scripts for building (including Node and browser bundles), testing, linting, and formatting. Use these commands during development.

```bash
# Build
pnpm build                 # Full build (Node + browser bundle)
pnpm build:node            # TypeScript compilation only
pnpm build:browser         # RSBuild browser/UMD bundle
pnpm clean                 # Remove dist directory

# Testing
pnpm test                  # Build and run vitest suite
pnpm tsc-check-tests       # TypeScript check test files

# Linting & Formatting
pnpm lint                  # Oxlint check (type-aware)
pnpm lint:fix              # Auto-fix linting issues
pnpm format                # oxfmt format
pnpm format:check          # oxfmt check
```

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

### get() method signature

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

TypeScript signature for the get() method that retrieves user data.

```typescript
async get(): Promise<User>
```

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

### get() method signature

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

Signature for the get() method of ActorEnvVarClient. Returns an ActorEnvironmentVariable or undefined.

```typescript
async get(): Promise<ActorEnvironmentVariable | undefined>
```

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

### Adding a New Resource Client

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

Code examples for adding a new resource client, collection client, integrating into ApifyClient, and exporting types.

```typescript
// src/resource_clients/my_resource.ts
import { ApiClientSubResourceOptions } from '../base/api_client';
import { ResourceClient } from '../base/resource_client';

export class MyResourceClient extends ResourceClient {
    constructor(options: ApiClientSubResourceOptions) {
        super({
            resourcePath: 'my-resources',
            ...options,
        });
    }

    async get(): Promise<MyResource | undefined> {
        return this._get();
    }

    async update(newFields: MyResourceUpdate): Promise<MyResource> {
        return this._update(newFields);
    }

    async delete(): Promise<void> {
        return this._delete();
    }
}
```

```typescript
// src/resource_clients/my_resource_collection.ts
import { ApiClientSubResourceOptions } from '../base/api_client';
import { ResourceCollectionClient } from '../base/resource_collection_client';
import { PaginatedList } from '../utils';

export class MyResourceCollectionClient extends ResourceCollectionClient {
    constructor(options: ApiClientSubResourceOptions) {
        super({
            resourcePath: 'my-resources',
            ...options,
        });
    }

    async list(options?: MyResourceListOptions): Promise<PaginatedList<MyResource>> {
        return this._list(options);
    }

    async create(resource: MyResourceCreate): Promise<MyResource> {
        return this._create(resource);
    }
}
```

```typescript
// In src/apify_client.ts
myResource(id: string): MyResourceClient {
    return new MyResourceClient(this._subResourceOptions({ id }));
}

myResources(): MyResourceCollectionClient {
    return new MyResourceCollectionClient(this._options());
}
```

```typescript
// In src/index.ts
export { MyResourceClient } from './resource_clients/my_resource';
export { MyResourceCollectionClient } from './resource_clients/my_resource_collection';
export type { MyResource, MyResourceCreate, MyResourceUpdate } from './resource_clients/my_resource';
```

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

### Create dataset with schema and push item

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/dataset-collection-client.md

Creates a dataset with a schema, or falls back to an existing one. Then pushes an item to the dataset. Includes error handling.

```javascript
// Create a dataset with a schema, falling back to an existing one
try {
    const dataset = await client.datasets().getOrCreate('spreadsheet-like', {
        schema: { fields: [{ name: 'url', type: 'string' }] },
    });
    await client.dataset(dataset.id).pushItems([{ url: 'https://example.com' }]);
} catch (err) {
    console.error('getOrCreate failed', err);
}
```

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

### Initialize ApifyClient with API Token

Source: https://github.com/apify/apify-client-js/blob/master/docs/01_introduction/quick-start.md

Initialize the ApifyClient by providing your API token. Keep your API token secure and do not expose it on the client side.

```javascript
import { ApifyClient } from 'apify-client';

// Client initialization with the API token
const client = new ApifyClient({
    token: 'MY-APIFY-TOKEN',
});
```

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

### GET /v2/actors/{id}/versions/{v}/env-vars/{name}

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/endpoints.md

Gets a specific environment variable of an actor version.

```APIDOC
## GET /v2/actors/{id}/versions/{v}/env-vars/{name}

### Description
Gets a specific environment variable of an actor version.

### Method
GET

### Endpoint
/v2/actors/{id}/versions/{v}/env-vars/{name}

### Parameters
#### Path Parameters
- **id** (string) - Required - Actor ID or `username/actor-name`.
- **v** (string) - Required - Version number.
- **name** (string) - Required - Environment variable name.

### Response
#### Success Response (200)
- **ActorEnvironmentVariable** (object) - The environment variable object.

#### Response Example
```json
{
  "name": "string",
  "value": "string",
  "isSecret": false
}
```
```

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

### create()

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

Creates a new Actor with the provided configuration options.

```APIDOC
## create()

### Description
Creates a new Actor. Returns the created Actor.

### Method
create

### Endpoint
actors

### Parameters
#### Request Body
- **actor** (ActorCollectionCreateOptions) - Required - The Actor data

### Request Example
```javascript
const newActor = await client.actors().create({
    name: 'my-actor',
    title: 'My Actor',
    isPublic: false,
});
```

### Response
#### Success Response
- **Actor** (Actor) - The created Actor

#### Response Example
```json
{
  "id": "string",
  "name": "string",
  "title": "string"
}
```

### Errors
- **ApifyApiError** - On API validation failure
- **ow error** - When `actor` is not an object
```

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

### Get schedule log with ScheduleClient.getLog()

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/schedule-clients.md

Retrieves the schedule log via GET /v2/schedules/{id}/log. Returns undefined when the log is missing.

```ts
async getLog(): Promise<string | undefined>
```

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

### ApifyClient Constructor

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

Creates a new ApifyClient instance with the provided options. Validates the options object and throws an error for unknown or incorrect keys.

```APIDOC
## ApifyClient Constructor

### Description
Creates a new ApifyClient instance. The client acts as a factory, and every method returns a dedicated resource client that shares the underlying HttpClient, statistics, and logger.

### Method
Constructor

### Endpoint
`new ApifyClient(options)`

### Parameters
#### Constructor Options
- `options.baseUrl` (string) - Optional - API origin; default `'https://api.apify.com'`; `/v2` is appended.
- `options.publicBaseUrl` (string) - Optional - Public URLs origin; default `'https://api.apify.com'`; `/v2` is appended.
- `options.maxRetries` (number) - Optional - Retry attempts for retryable failures; default `8`.
- `options.minDelayBetweenRetriesMillis` (number) - Optional - Exponential backoff base delay in milliseconds; default `500`.
- `options.requestInterceptors` (RequestInterceptorFunction[]) - Optional - Extra Axios request interceptors; default `[]`.
- `options.timeoutSecs` (number) - Optional - Request timeout in seconds; default `360`.
- `options.token` (string) - Optional - Auth token, used as `Authorization: Bearer …`.
- `options.userAgentSuffix` (string | string[]) - Optional - Node `User-Agent` suffix.

### Request Example
```javascript
const { ApifyClient } = require('apify-client');

const client = new ApifyClient({
    token: 'MY-APIFY-TOKEN',
    maxRetries: 5,
    minDelayBetweenRetriesMillis: 250,
    timeoutSecs: 120,
});
```

### Response
#### Success Response
The constructor returns an `ApifyClient` instance with the following fields:
- `baseUrl` (string) - Normalized API base URL (`<baseUrl>/v2`).
- `publicBaseUrl` (string) - Normalized public base URL (`<publicBaseUrl>/v2`) — used for signed public URLs.
- `token` (string | undefined) - The API token.
- `stats` (Statistics) - Telemetry (`calls`, `requests`, `rateLimitErrors`).
- `logger` (Log) - Logger with prefix `ApifyClient`.
- `httpClient` (HttpClient) - Shared HTTP client.

#### Error
Throws an `ow` validation error for unknown or incorrect option keys.

```

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

### List schedules with ScheduleCollectionClient.list()

Source: https://github.com/apify/apify-client-js/blob/master/_autodocs/api-reference/schedule-clients.md

Lists schedules with pagination options. The example shows listing with descending order and a limit of 5 items.

```ts
list(options: ScheduleCollectionListOptions = {}): PaginatedIterator<Schedule>
```

```javascript
const { items } = await client.schedules().list({ desc: true, limit: 5 });
```

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

### update() usage example

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

Updates the title of a dataset.

```javascript
await client.dataset('my-dataset').update({ title: 'Crawl results' });
```
Tokens:
Raw