Skip to main content
Version: Next

externalApifyClient

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

externalconstructor

  • 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

    • externaloptionaloptions: ApifyClientOptions

      Configuration of the client and of its HTTP client.

    Returns ApifyClient

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

Properties

externalbaseUrl

baseUrl: string

externallogger

logger: Log

externalpublicBaseUrl

publicBaseUrl: string

Added in 2.17.0

externalstats

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.

externaloptionaltoken

token?: string

Accessors

externalhttpClient

  • 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

    • externalhttpClient: HttpClient

    Returns void

Methods

externalactor

  • actor(id): ActorClient

  • 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

    • externalid: 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

externalactors

  • actors(): ActorCollectionClient

  • Returns a client for managing Actors in your account.

    Provides access to the Actor collection, allowing you to list, create, and search for Actors.

    Returns ActorCollectionClient

    A client for the Actors collection

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

externalbuild

  • build(id): BuildClient

  • Returns a client for a specific Actor build.

    Use this to get details about a build, wait for it to finish, or access its logs.

    Parameters

    • externalid: string

      Build ID

    Returns BuildClient

    A client for the specified build

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

externalbuilds

  • builds(): BuildCollectionClient

externaldataset

  • dataset<Data>(id): DatasetClient<Data>

  • 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

    • externalid: 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

externaldatasets

  • datasets(): DatasetCollectionClient

  • Returns a client for managing datasets in your account.

    Datasets store structured data results from Actor runs. Use this to list or create datasets.

    Returns DatasetCollectionClient

    A client for the Datasets collection

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

externalkeyValueStore

  • keyValueStore(id): KeyValueStoreClient

  • 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

    • externalid: 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

externalkeyValueStores

  • keyValueStores(): KeyValueStoreCollectionClient

  • Returns a client for managing key-value stores in your account.

    Key-value stores are used to store arbitrary data records or files.

    Returns KeyValueStoreCollectionClient

    A client for the Key-value stores collection

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

externallog

  • log(buildOrRunId): LogClient

  • Returns a client for accessing logs of an Actor build or run.

    Parameters

    • externalbuildOrRunId: string

      Build ID or run ID

    Returns LogClient

    A client for accessing logs

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

externalrequestQueue

  • requestQueue(id, options): RequestQueueClient

  • 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

    • externalid: string

      Request queue ID or name

    • externaloptionaloptions: 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

externalrequestQueues

  • requestQueues(): RequestQueueCollectionClient

  • Returns a client for managing request queues in your account.

    Request queues store URLs to be crawled, along with their metadata.

    Returns RequestQueueCollectionClient

    A client for the Request queues collection

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

externalrun

  • run(id): RunClient

  • 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

    • externalid: 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

externalruns

  • runs(): RunCollectionClient

externalschedule

  • schedule(id): ScheduleClient

  • Returns a client for a specific schedule.

    Use this to get, update, or delete a schedule.

    Parameters

    • externalid: string

      Schedule ID

    Returns ScheduleClient

    A client for the specific Schedule

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

externalschedules

  • schedules(): ScheduleCollectionClient

  • Returns a client for managing schedules in your account.

    Schedules automatically start Actor or task runs at specified times.

    Returns ScheduleCollectionClient

    A client for the Schedules collection

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

externalsetStatusMessage

  • 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

    • externalmessage: string

      The status message to set

    • externaloptionaloptions: 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

externalstore

  • store(): StoreCollectionClient

  • Returns a client for browsing Actors in Apify Store.

    Use this to search and retrieve information about public Actors.

    Returns StoreCollectionClient

    A client for the Apify Store

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

externaltask

  • task(id): TaskClient

  • Returns a client for a specific Actor task.

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

    Parameters

    • externalid: 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

externaltasks

  • tasks(): TaskCollectionClient

  • Returns a client for managing Actor tasks in your account.

    Tasks are pre-configured Actor runs with stored input that can be executed repeatedly.

    Returns TaskCollectionClient

    A client for the task collection

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

externaluser

  • user(id): UserClient

  • Returns a client for accessing user data.

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

    Parameters

    • externaloptionalid: string

      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

externalwebhook

  • webhook(id): WebhookClient

  • Returns a client for a specific webhook.

    Use this to get, update, delete, or test a webhook.

    Parameters

    • externalid: string

      Webhook ID

    Returns WebhookClient

    A client for the specific webhook

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

externalwebhookDispatch

  • webhookDispatch(id): WebhookDispatchClient

externalwebhookDispatches

  • webhookDispatches(): WebhookDispatchCollectionClient

  • Returns a client for viewing webhook dispatches in your account.

    Webhook dispatches represent individual invocations of webhooks.

    Returns WebhookDispatchCollectionClient

    A client for the webhook dispatches collection

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

externalwebhooks

  • webhooks(): WebhookCollectionClient

  • Returns a client for managing webhooks in your account.

    Webhooks notify external services when specific events occur (e.g., Actor run finishes).

    Returns WebhookCollectionClient

    A client for the Webhooks collection

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

staticexternalwithCustomHttpClient

  • 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

    • externaloptions: ApifyClientCustomHttpClientOptions

      The token, the API URLs and the HTTP client to use.

    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