Skip to main content
Version: Next

ApifyClient

The official JavaScript client for the Apify API.

Provides programmatic access to all Apify platform resources including Actors, runs, datasets, key-value stores, request queues, and more. Works in both Node.js and browser environments.

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'my-token' });

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

// Fetch dataset items
const { items } = await client.dataset(run.defaultDatasetId).listItems();

See more at https://docs.apify.com/api/v2

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

  • Creates a client that sends its requests through the built-in AxiosHttpClient, configured from options: the API token, retries, the timeout tiers, request compression and default headers. The HTTP client itself is created when httpClient is first read. To send the requests through a custom HTTP client, use ApifyClient.withCustomHttpClient instead.

    Parameters

    Returns ApifyClient

    Throws - When an option is unknown or has an invalid value.

Properties

baseUrl

baseUrl: string

logger

logger: Log

publicBaseUrl

publicBaseUrl: string

Added in 2.17.0

stats

stats: Statistics

Statistics of the API calls made through the client. With a custom HTTP client, this is the client's own stats object, so it only reflects what that client records.

optionaltoken

token?: string

Accessors

httpClient

  • get httpClient(): HttpClient
  • set httpClient(httpClient): void

  • The HTTP client the requests go through: the custom one when set through ApifyClient.withCustomHttpClient, and otherwise an AxiosHttpClient configured from the constructor options, created on first access. Assigning a client applies token to it through HttpClient.setDefaultAuthorization and points stats at its statistics, so the counters keep tracking the calls the client actually makes. Resource clients hold on to the HTTP client they were created with, so assign before reaching for them. Assigning does not close the client it replaces. A default client that already sent a request keeps its keep-alive agents open until HttpClient.close is called on it, so close it yourself, or assign before the first request.

    Returns HttpClient

  • Parameters

    Returns void

Methods

actor

  • Returns a client for a specific Actor.

    Use this to get, update, delete, start, or call an Actor, as well as manage its builds, runs, versions, and webhooks.

    Parameters

    • id: string

      Actor ID or username/name

    Returns ActorClient

    A client for the specific Actor

    // Call an Actor and wait for it to finish
    const run = await client.actor('apify/web-scraper').call({ url: 'https://example.com' });

    See more at https://docs.apify.com/api/v2/act-get

actors

build

builds

dataset

  • Returns a client for a specific dataset.

    Use this to read, write, and manage items in the dataset. Datasets contain structured data stored as individual items (records).

    Parameters

    • id: string

      Dataset ID or name

    Returns DatasetClient<Data>

    A client for the specific Dataset

    // Push items to a dataset
    await client.dataset('my-dataset').pushItems([
      { url: 'https://example.com', title: 'Example' },
      { url: 'https://test.com', title: 'Test' }
    ]);

    // Retrieve items
    const { items } = await client.dataset('my-dataset').listItems();

    See more at https://docs.apify.com/api/v2/dataset-get

datasets

keyValueStore

  • Returns a client for a specific key-value store.

    Use this to read, write, and delete records in the store. Key-value stores can hold any type of data including text, JSON, images, and other files.

    Parameters

    • id: string

      Key-value store ID or name

    Returns KeyValueStoreClient

    A client for the specific key-value store

    // Save a record
    await client.keyValueStore('my-store').setRecord({ key: 'OUTPUT', value: { foo: 'bar' } });

    // Get a record
    const record = await client.keyValueStore('my-store').getRecord('OUTPUT');

    See more at https://docs.apify.com/api/v2/key-value-store-get

keyValueStores

log

requestQueue

  • Returns a client for a specific request queue.

    Use this to add, retrieve, and manage requests in the queue. Request queues are used by web crawlers to manage URLs that need to be visited.

    Parameters

    • id: string

      Request queue ID or name

    • options: RequestQueueUserOptions = {}

      Configuration options for the request queue client

    Returns RequestQueueClient

    A client for the specific Request queue

    // Add requests to a queue
    const queue = client.requestQueue('my-queue');
    await queue.addRequest({ url: 'https://example.com', uniqueKey: 'example' });

    // Get and lock the next request
    const { items } = await queue.listAndLockHead({ lockSecs: 60 });

    See more at https://docs.apify.com/api/v2/request-queue-get

requestQueues

run

  • Returns a client for a specific Actor run.

    Use this to get details about a run, wait for it to finish, abort it, or access its dataset, key-value store, and request queue.

    Parameters

    • id: string

      Run ID

    Returns RunClient

    A client for the specified run

    // Wait for a run to finish
    const run = await client.run('run-id').waitForFinish();

    // Access run's dataset
    const { items } = await client.run('run-id').dataset().listItems();

    See more at https://docs.apify.com/api/v2/actor-run-get

runs

schedule

schedules

setStatusMessage

  • setStatusMessage(message, options): Promise<void>

  • Sets a status message for the current Actor run.

    This is a convenience method that updates the status message of the run specified by the ACTOR_RUN_ID environment variable. Only works when called from within an Actor run.

    Parameters

    • message: string

      The status message to set

    • optionaloptions: SetStatusMessageOptions

      Additional options for the status message

    Returns Promise<void>

    Throws - If ACTOR_RUN_ID environment variable is not set

    Added in 2.7.0

store

task

  • Returns a client for a specific Actor task.

    Use this to get, update, delete, or run a task with pre-configured input.

    Parameters

    • id: string

      Task ID or username/task-name

    Returns TaskClient

    A client for the specified task

    // Run a task and wait for it to finish
    const run = await client.task('my-task').call();

    See more at https://docs.apify.com/api/v2/actor-task-get

tasks

user

  • Returns a client for accessing user data.

    By default, returns information about the current user (determined by the API token).

    Parameters

    • id: string = ME_USER_NAME_PLACEHOLDER

      User ID or username. Defaults to 'me' (current user)

    Returns UserClient

    A client for the user

    See more at https://docs.apify.com/api/v2/user-get

webhook

webhookDispatch

webhookDispatches

webhooks

staticwithCustomHttpClient

  • Creates an ApifyClient that sends its requests through a custom HTTP client.

    The custom client owns its transport configuration: retries, timeouts, default headers and whatever its transport needs are set on the client itself. This is also how the built-in AxiosHttpClient is configured beyond what the constructor options offer, for example with axios request interceptors. The token is set as the client's Authorization header, unless the client already has one configured.

    Parameters

    Returns ApifyClient

    A client whose httpClient is the given one.

    import { ApifyClient, HttpClient } from 'apify-client';

    class MyHttpClient extends HttpClient {
        async sendRequest({ method, url, headers, body, timeoutMillis, stream, signal }) {
            // Send the request with the HTTP library of your choice and return { status, headers, body }.
        }
    }

    const client = ApifyClient.withCustomHttpClient({ token: 'my-token', httpClient: new MyHttpClient() });
Page Options