Version: Next

Quick start

Learn how to authenticate, run Actors, and retrieve results using the Apify API client for JavaScript.

Step 1: Authenticate the client

To use the client, you need an API token. You can find your token under the Integrations tab in Apify Console. Copy the token and initialize the client by providing it (MY-APIFY-TOKEN) as a parameter to the ApifyClient constructor.

import { ApifyClient } from 'apify-client';

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

Secure access

The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so don't share your API token with untrusted parties or expose it on the client side of your applications.

Step 2: Run an Actor

To start an Actor, call the client.actor() method with the Actor's ID (e.g. john-doe/my-cool-actor). The Actor's ID is a combination of the Actor owner's username and the Actor name. You can run both your own Actors and Actors from Apify Store.

To define the Actor's input, pass an object to the call() method that matches the Actor's input schema. The input can include URLs to scrape, search terms, or other configuration data.

import { ApifyClient } from 'apify-client';

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

// Define the input for the Actor.
const input = { some: 'input' };

// Start an Actor and wait for it to finish.
const run = await client.actor('username/actor-name').call(input);

Step 3: Get results from the dataset

To get the results from the dataset, call the client.dataset() method with the dataset ID, then call listItems() to retrieve the data. You can get the dataset ID from the defaultDatasetId field of the Run object returned by call().

import { ApifyClient } from 'apify-client';

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

// Start an Actor and wait for it to finish.
const { defaultDatasetId } = await client.actor('username/actor-name').call();

// List items from the Actor's dataset.
const { items } = await client.dataset(defaultDatasetId).listItems();
console.log(items);

Dataset access

Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response, you should access the existing dataset of the finished Actor run.

Next steps

Concepts

To learn more about how the client works, check out the Concepts section in the sidebar:

Single and collection clients - resource clients and collection clients
Error handling - API errors and how to tell them apart
Retries - automatic retries with exponential backoff
Pagination - iterating through large result sets
Typed models - response types and validation

Guides

For practical examples of common tasks, see the Guides section: